OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide Abstract This guide describes the Compaq Open Systems Interconnection/Message Handling System (OSI/MHS) Gateway Programmatic Interface (GPI), which is the Compaq implementation of the X.400 Gateway Application Program Interface (X.400). The GPI provides a programmatic interface to Compaq OSI/MHS at the message transfer agent (MTA) boundary. This guide provides an overview of the GPI components and operation.
Document History Part Number Product Version Published 063973 February 1992 132296 OSI/MHS C30 OSI/MHS C32 OSI/MHS D20 OSI/MHS D22 OSI/MHS D41 424822-001 OSI/MHS D42 December 1999 088588 099111 113063 March 1993 September 1993 June 1995 February 1997 Ordering Information For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact your local sales representative.
OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide Glossary Index Figures Tables What’s New in This Manual ix Manual Information ix New and Changed Information ix About This Manual xi Who Should Read This Manual? xi What’s in This Manual? xi What Related Publications Are Available? xii Your Comments Invited xv Notation Conventions xvi Abbreviations xix 1. Introduction X.
2. The GPI Library Contents 2. The GPI Library Library Procedures 2-1 Environment Management Procedures 2-2 Object Management Procedures Message Transfer Procedures 2-4 2-7 Declaration Files 2-11 Data Declaration Files 2-11 Procedure Declaration Files 2-12 3. GPI Object Management GPI Object Management Features 3-1 3-2 How Objects Work Properties of Objects 3-2 Objects and X.
4. Planning Your Program (continued) Contents 4. Planning Your Program (continued) GIP Configuration 4-5 Gateway Password 4-5 Using Extensions and Criticality 4-5 Supported Extensions 4-6 Unsupported Extensions 4-8 EDI Extensions 4-8 5.
. Recovering From Errors (continued) Contents 6. Recovering From Errors (continued) Recovering From a Client Failure 6-22 Recovering From Fatal and Internal GPI Errors 6-22 Common GPI Errors 6-22 A. TAL Program Example B. C Program Example C. Review of X.400 and OSI/MHS X.400 C-1 X.400 Messages C-2 Compaq OSI/MHS C-3 X.400 Gateways C-3 D. EDI Concepts What Is Electronic Data Interchange (EDI)? D-1 EDI Messaging System (EDIMS) EDI Message (EDIM) Structure EDIMs and X.
Figures (continued) Contents Figures (continued) Figure 1-6. Outbound Processing 1-7 Figure 1-7. Outbound Processing 1-8 Figure 1-8. Inbound Processing (Normal Type Gateway) 1-8 Figure 1-9. NORMAL Inbound Information Flow Figure 1-10. Message Flow in a P1-EXIT Type Gateway 1-11 Figure 2-1. GPI Program Flow: Environment Management Procedures 2-3 Figure 2-2. Object, Attribute, and Attribute Descriptor Figure 2-3. GPI Program Flow: Object Management Procedures 2-5 Figure 2-4.
Figures (continued) Contents Figures (continued) Figure 5-8. Using GPI_MT_START_TRANSFER_IN_ With Decoded Root Objects 5-30 Figure 5-9. Using GPI_OM_FETCH_ Figure 5-10. Using GPI_OM_EXAMINE_ Figure 5-11. Using GPI_OM_LIST_ Figure 5-12. Using GPI_OM_READ_ Figure 5-13. Using GPI_MT_FINISH_TRANSFER_IN_ Figure 5-14. Using GPI_OM_REMOVE_ Figure 6-1. Flow Diagram for GPI Error-Checking Figure 6-2. Flow Diagram for GPI Diagnostics Figure 6-3. Information Buffer Parameters 6-10 Figure 6-4.
Tables (continued) Contents Tables (continued) Table 3-2. GPI Object Classes (page 1 of 2) 3-9 Table 3-3. Attribute Syntaxes Table 4-1. Responsibility for Outbound Information Table 4-2. Responsibility for Inbound Information 4-4 Table 4-3. Supported Extensions Table 5-1. Sequence of GPI Procedures Table 5-2. Sequence for Building a Root Object 5-16 Table 5-3. Sequence for Retrieving Information From a Root Object 5-32 Table 6-1. GPI_STATUS_ Error Classes (page 1 of 2) Table C-1. X.
Contents OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide —424822-001 viii
What’s New in This Manual Manual Information Abstract This guide describes the Compaq Open Systems Interconnection/Message Handling System (OSI/MHS) Gateway Programmatic Interface (GPI), which is the Compaq implementation of the X.400 Gateway Application Program Interface (X.400). The GPI provides a programmatic interface to Compaq OSI/MHS at the message transfer agent (MTA) boundary. This guide provides an overview of the GPI components and operation.
What’s New in This Manual New and Changed Information OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide —424822-001 x
About This Manual This manual describes the Compaq OSI/MHS Gateway Programmatic Interface (GPI), which is the Compaq implementation of the X.400 Gateway Application Program Interface (X.400 API). The GPI provides a programmatic interface to the Compaq Open Systems Interconnection/Message Handling System (OSI/MHS) at the message transfer agent (MTA) boundary. This manual provides a detailed overview of GPI components and operation. It also describes how to plan, write, and debug a program which uses the GPI.
About This Manual • • • • What Related Publications Are Available? Appendix C, Review of X.400 and OSI/MHS, is a brief review of key X.400 and OSI/MHS concepts. For programmers new to networking, it provides a quick orientation to the GPI gateway environment. Appendix D, EDI Concepts, provides a quick orientation to GPI support of EDI. Glossary contains definitions of GPI terms used in this guide and in related OSI/MHS manuals.
Programming Manuals About This Manual Programming Manuals For information about calling procedures from TAL and C programs, see the following Compaq manuals: • • Transaction Application Language (TAL) Reference Manual C/C++ Programmer’s Guide Figure i shows the related Compaq publications. Figure i. Related Manuals X.
About This Manual Other OSI/MHS Manuals Other OSI/MHS Manuals The following manuals provide additional information about Compaq OSI/MHS: • • • • • • • • Message Handling Systems Orientation Guide describes common tasks involved in building message handling systems with Compaq products. It also helps you to find related information in other Compaq manuals and educational offerings.
Your Comments Invited About This Manual Figure ii shows the manuals of the Compaq OSI/MHS library and the type of information contained in each manual. Figure ii.
About This Manual Notation Conventions A Reader Comment Card is located at the back of printed manuals and as a separate file on the User Documentation disc. You can either fax or mail the card to us. The fax number and mailing address are provided on the card. Also provided on the Reader Comment Card is an Internet mail address. When you send an Internet mail message to us, we immediately acknowledge receipt of your message. A detailed response to your message is sent as soon as possible.
About This Manual General Syntax Notation { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list may be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON | OFF } | Vertical Line.
Notation for Messages About This Manual !i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data to the called procedure); the !o notation follows an output parameter (one that returns data to the calling program). For example: CALL CHECKRESIZESEGMENT ( segment-id , error ) ; !i !o !i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both passes data to the called procedure and returns data to the calling program).
About This Manual Abbreviations [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For example: Event number = number [ Subject = first-subject-value ] A group of items enclosed in brackets is a list of all possible items that can be displayed, of which one or none might actually be displayed.
About This Manual Abbreviations BER. Basic encoding rules CCITT. International Telegraph and Telephone Consultative Committee DDL. Data Definition Language (Compaq term) DSM. Distributed Systems Management (Compaq term) EDI. electronic data interchange EDIM. EDI message EDIMG. EDI messaging EDIMS. EDI messaging system EDIN. EDI notification EDI-MS. EDI message store EDI-UA. EDI user agent EIT. Encoded information type G3. Group 3 (facsimile) G4. Group 4 (facsimile) GIP.
About This Manual Abbreviations MHS. Message handling system MOTIS. Message-Oriented Text Interchange System MPDU. Message protocol data unit MR. Message relay MRP. Message relay process MS. Message store MTA. Message transfer agent MTS. Message transfer system NBPS. Nonbasic parameters OM. Object management O/R. Originator/recipient OSI. Open Systems Interconnection OSI/MHS. Open Systems Interconnection/Message Handling System (Compaq term) P1. Protocol 1 (message-transfer protocol) P2.
About This Manual Abbreviations TAL. Transaction Application Language (Compaq term) TMF. Transaction Management Facility (Compaq term) UA. User agent UTC. Universal Coordinated Time XAPIA. X.
1 Introduction The Compaq Gateway Programmatic Interface (GPI) presents proprietary message systems with a standard interface to X.400 networks (Figure 1-1). Figure 1-1. A Gateway Links Two Networks Proprietary Message System Gateway Client X.400 Network MTA GPI CDT 101.CDD There are two distinct types of GPI gateway: NORMAL and P1-EXIT. In the NORMAL case, the GPI and a proprietary client program constitute a gateway between the proprietary message system and the X.400 network.
Introduction Compaq GPI Briefly, the template has two key features: • • An information architecture based on object-oriented structures (objects) A set of services to manage and transfer objects Objects are structures that contain the X.400 information. A root object is a special structure that contains an entire X.400 message, probe, report, or P1-encoded object. The API supplies procedures that manipulate the objects in a well-defined manner.
Introduction • • Process Architecture A flexible architecture, useful for many applications Full control over gateway P1 and P2 facilities Process Architecture In exchanging messages between a proprietary system and an X.400 system, the GPI makes use of the queue manager and several entities in the OSI/MHS subsystem. A view of the complete gateway environment is shown in Figure 1-3. Figure 1-3. The Gateway Environment Compaq System Proprietary System Message GPI X.
Introduction Client Program Client Program The client program consists of client code bound to GPI library components. You can configure and manage the client program in any manner supported by Compaq. A client program is required to provide the fully qualified name of a specific MHS manager process to the GPI_OPEN_ procedure. A client program is also required to pass the gateway password and the name of the GATEWAY object that the client’s APPL objects are associated with.
Introduction GIP The GPI library includes: • Procedures that are used to: • • • • • • Manage objects Transfer root objects in or out Report errors Control the gateway Declaration files for the procedures Parameters to procedure calls GIP The GIP connects the gateway to processes within the OSI/MHS subsystem. At run time, this process provides access to input and output message queues associated with the OSI/MHS MTA to which the GPI connects.
Introduction Queue Manager fundamental part of an OSI/MHS subsystem. The MRP, together with the RTS, is responsible for routing communications into and out of the gateway. When the MR group starts, the gateway access unit (GAU), which is within the MRP, establishes a connection with the entry manager process in the queue manager. This connection is used for subsequent inbound operations. MR groups are configured and managed by the OSI/MHS manager process.
Introduction NORMAL Outbound Processing Figure 1-5. Inbound and Outbound Directions Outbound Client OSI/MHS MTA Inbound CDT 105.CDD NORMAL Outbound Processing Outbound processing is done on information outbound from the client to X.400. The information originates as a proprietary system message (Figure 1-7). Figure 1-6. Outbound Processing (Proprietary Message Here) Proprietary Message System X.
Introduction NORMAL Inbound Processing 6. The MRP transfers the outbound root object to the RTS which routes the object to the appropriate destination. Figure 1-7. Outbound Processing Compaq System Queue Manager GPI X.400 Gateway Proprietary System Message Wait Manager Entry Manager Queue File 2 1 GPI Library Client GIP 3 OSI/MHS Subsystem MR Group MHS Manager 4 PDU Store X.400 Message 5 6 RTS MRP 6 CDT 107.CDD NORMAL Inbound Processing Figure 1-8.
Introduction P1-EXIT Message Flow 1. The RTS receives a root object (representing a message, probe, report, or P1-encoded object). The RTS places the root object on the PDU store and informs the MRP. 2. The MRP reads the root object to determine the destination. 3. If the root object is addressed to this GPI gateway, the MRP notifies the queue manager. 4. If a wait is pending, the queue manager notifies the GIP that an inbound root object is available.
Introduction P1-EXIT Message Flow One of the gateway object’s attributes is TYPE. There are two types: NORMAL and P1-EXIT. The NORMAL type gateway is the standard case described in the preceding pages of this section. The two types of gateway are very different. The system administrator or the installer of the gateway determines the gateway’s type when the gateway is configured. For complete information on configuring gateways, refer to the OSI/MHS Configuration and Management Manual. X.
Introduction P1-EXIT Message Flow The MH-TRANSFER option is used if no changes are to be made to the root object. In this case, the client wants the root object to be treated like an outbound message, so it puts the message on the outbound queue: The GIP notifies the MRP of an outbound root object in the MR group PDU store. 7. The MRP reads the outbound root object in the MR group PDU store. 8. The MRP routes the outbound root object to the appropriate destination.
Introduction P1-EXIT Message Flow OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 1-12
2 The GPI Library The GPI library procedural interface consists of 18 library procedures and four declaration files. The library procedures allow the client program to manage objects, transfer root objects, report errors, and control the gateway. The declaration files define the procedures and their parameters. This section provides a basic understanding of these GPI library components.
The GPI Library Environment Management Procedures Table 2-1. GPI Library Procedures (page 2 of 2) Environment Management Object Management Message Transfer GPI_STATUS_ GPI_OM_REMOVE_ GPI_MT_FINISH_TRANSFER_IN_ GPI_OM_DELETE_ GPI_OM_EXAMINE_ GPI_OM_FETCH_ GPI_OM_LIST_ GPI_OM_READ_ GPI_OM_COPY_ All GPI procedures share the following characteristics: • • Each has a status parameter that indicates the outcome of the procedure call.
The GPI Library Environment Management Procedures an internal workspace necessary for other GPI procedures to operate correctly. It has parameters that allow you to tailor the workspace to your gateway needs. The workspace is a memory segment dedicated to the GPI library. The segment stores operational information such as the identity of current GPI sessions and recent errors. The segment also provides memory space for object management. All other GPI procedures use this GPI library memory space.
The GPI Library Object Management Procedures GPI_STATUS_ can be used as the core for a GPI diagnostic routine. GPI diagnostics are described in detail in Section 6, Recovering From Errors. Object Management Procedures After a session is established, you can use object management and message transfer procedures. This is done within the context of outbound and inbound processing. Object management procedures allow the client to manipulate objects in the GPI library memory space.
The GPI Library Object Management Procedures resolved into object structures that themselves are composed of other attributes. This XAPIA concept is fully described in Section 3, GPI Object Management. The four types of object management procedures are shown in Figure 2-3. Procedures from each type are typically used at different points in the program, as described in following subsections. GPI_OM_CREATE_ , GPI_OM_INSERT_ , and GPI_OM_WRITE_ Composing procedures are listed in Table 2-3.
The GPI Library Object Management Procedures The GPI_OM_CREATE_ procedure creates a new object of a specified class. Optionally, it can also add to this object a set of default attributes and their values. GPI_OM_CREATE_ returns an object identifier for the newly created object; you refer to this identifier in all procedure calls that operate on the object. The GPI_OM_INSERT_ procedure adds attribute values to an object.
The GPI Library Message Transfer Procedures Table 2-5.
The GPI Library Message Transfer Procedures GPI_MT_TRANSFER_OUT_ The GPI_MT_TRANSFER_OUT_ procedure transfers a root object from GPI library memory space to the output queue of the GPI service. As the object passes through the GIP, it is encoded into a form suitable for eventual transfer to the X.400 network. GPI_MT_WAIT_ The GPI_MT_WAIT_ procedure is used prior to inbound transfer. GPI_MT_WAIT_ monitors the input queue of the GPI service for a specified time.
The GPI Library Message Transfer Procedures Figure 2-4.
The GPI Library Message Transfer Procedures During the transfer-in stages, a root object on the input queue and its corresponding object in GPI library memory have states. To best understand the two transfer-in procedures, you need an understanding of the states at each stage. Prior to a call to GPI_MT_START_TRANSFER_IN_ , a root object on the input queue is unreserved (Figure 2-5). It is available to any client that can access the queue.
The GPI Library Declaration Files Declaration Files The declaration files provide definitions for the GPI library procedures and for data types that are used as parameters to GPI procedure calls. The name and contents of each declaration file are listed in Table 2-7. Table 2-7.
The GPI Library Procedure Declaration Files Table 2-8.
3 GPI Object Management XAPIA objects are structures that represent collections of information. Within the gateway, objects represent X.400 messages or their parts. Using calls to the GPI service, the client program manages objects in GPI library memory space. This section provides a basic explanation of objects and how to use them.
GPI Object Management How Objects Work Table 3-1. GPI Object Management Procedures (page 2 of 2) Procedure Name Purpose GPI_OM_READ_ Reads a segment of a data string from a value of an attribute GPI_OM_REMOVE_ Removes and discards attribute values of an object GPI_OM_WRITE_ Writes a segment of a data string to a value of an attribute How Objects Work The purpose of objects is to shield the client from the complexity of native X.400 format. The client does not operate on “raw” X.
GPI Object Management Properties of Objects Figure 3-1. Objects and Attributes OBJECT OBJECT Attribute Attribute Attribute Attribute Attribute Attribute Attribute Attribute Attribute Attribute OBJECT Attribute Attribute CDT 301.CDD Objects Can Contain Other Objects An object might have an attribute that represents another object. In this sense, an object can contain another object (Figure 3-2). In effect, the contained object is on a level subordinate to the object that contains it.
GPI Object Management Objects and X.400 Messages Objects Are Grouped Into Classes Within XAPIA specifications, objects are categorized into classes based on the attribute types contained in the objects. Attribute types are described later in Attribute Type on page 3-11. For example, suppose there are five types, named A, B, C, D, and E. As shown in Figure 3-3, objects that have attributes of types A and B are grouped into a class called X.
GPI Object Management Objects and X.400 Messages Figure 3-4. X.400 Message as Object Message MH-C-MESSAGE MH-T-BILATERAL-INFORMATION MH-T-EXTERNAL-TRACE-INFO Message Envelope MH-T-MTS-IDENTIFIER MH-T-ORIGINAL-EITS MH-T-ORIGINATOR-NAME MH-T-RECIPIENT-DESCRIPTORS MH-T-PRIORITY MH-T-CONTENT-IDENTIFIER MH-T-CONTENT-TYPE MH-T-DISCLOSURE-ALLOWED MH-T-CONVERSION-PROHIBITED Message Content MH-T-ALTERNATE-RECIP-ALLOWED MH-T-CONTENT-RETURN-REQUESTED MH-T-CONTENT CDT 304.
GPI Object Management Objects and X.400 Messages Figure 3-5. Partial Object Representation MESSAGE Bilateral Information BILATERAL INFORMATION ADMD Name Country Name Information External Trace Info EXTERNAL TRACE ENTRY ADMD Country Name Country Name PRMD Identifier Action Arrival Time MTS Identifier Original EITS Originator Name Recipient Descriptors Priority Content Identifier Content Type Disclosure Allowed Conversion Prohibited Alternate Recip Allowed Content Return Requested Content CDT 305.
GPI Object Management Objects and Object Classes Figure 3-6.
GPI Object Management Object Identifiers Object Identifiers When the client creates or copies an object, the GPI assigns a unique object identifier to that object. You use the object identifier to refer to the object in calls to procedures that operate on it. For example, when you transfer an object to the output queue, you specify its object identifier. Following are some important considerations about object identifiers: • • The identifier references all information represented by the object.
GPI Object Management Object Classes Table 3-2.
GPI Object Management Root Objects Table 3-2. GPI Object Classes (page 2 of 2) MH Classes IM Classes EDI Classes EDI-C-SERV-STRING-ADVICE EDI-C-SYNTAX-ID Note: The GPI supports only one OM class, OM-C-EXTERNAL (not listed). When using GPI_OM_CREATE_ to create an object, you specify the desired object class as a parameter. If the GPI_OM_CREATE_ initialize parameter is set to OM-TRUE, the object is filled with default first-level attributes for that class.
GPI Object Management Attributes Attributes Until now, this section has focused on objects. Now it focuses on attributes, the fundamental units of objects. Each attribute represents a separate information item. As shown in Figure 3-8, an information item has three components: type, syntax, and one or more attribute values. Figure 3-8. Attribute Information Attribute Type Syntax Value 0 ••• Value n INFORMATION ITEM CDT 308.CDD Attribute Type An attribute type is a name for an attribute.
GPI Object Management Attribute Value Table 3-3. Attribute Syntaxes Syntax Values Represented Boolean TRUE or FALSE. Enumeration Any of a specified set. Integer The positive and negative integers represented in 32 bits. Object Object identifier of a specified class. String Any of the following well-defined strings: bit, encoding, IA5, numeric, object descriptor, object identifier, octet, printable, teletex, UTC time, videotex (each has its own constant).
GPI Object Management Attribute Descriptor Lists Attribute Descriptor Lists Each attribute value requires a separate description. For a multivalued attribute, or several single-valued attributes, several descriptors are required. A collection of descriptors is called a descriptor list (Figure 3-10). Here, descriptors 0 and 1 are for single-valued attributes; descriptors 2, 3, and 4 correspond to a multivalued attribute. Figure 3-10.
GPI Object Management Attribute Position and Value Position Figure 3-11. Attribute Position and Value Position OBJECT X (OBJECT_X_ID) ••• OM-T-Class 0 OM-S-Integer Object X Attribute Type A 1 OM-S-Object Object_Y_ID Attribute Type C 2 Syntax of C Value 0 of C Value 1 of C Value 2 of C Value 3 of C Attribute Type H 3 Syntax of H Value of H OBJECT Y (OBJECT_Y_ID) OM-T-Class 0 OM-S-Integer Object Y Attribute Type H 1 Syntax of H Value of H Attribute Type W 18 Syntax of W Value of W CDT 311.
GPI Object Management Attribute Position and Value Position The integer constant is part of the DDL definition for each attribute type. A complete listing of the DDL definitions is provided in the GPI Reference Manual.
GPI Object Management Attribute Position and Value Position OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 3- 16
4 Planning Your Program There are a number of things to consider before writing a GPI client program. For instance, you need to consider how to handle gateway fault recovery, security, and protocol changes. You also need to decide if you want to implement multiple GPI sessions, and if so, how to do so. Of course, it’s also necessary to verify that the software required for GPI operation is installed and configured.
Planning Your Program • Planning for Multiple GPI Sessions Using the SCF START command, you start the APPL, GI CLASS, and GI GROUP objects that you have defined. Note. SCF objects do not relate to the XAPIA objects used by the GPI procedural interface.
Planning Your Program Planning for Gateway Fault Recovery Figure 4-1. GPI Sessions and Gateways Compaq System GPI X.400 Gateway Session 1 GIP Client GPI Library Session 2 GIP Session 3 GIP GATEWAY Object X GATEWAY Object Y GATEWAY Object Z Up to 15 sessions CDT 401.CDD Planning for Gateway Fault Recovery You can configure and manage the client program in any manner supported by Compaq.
Planning Your Program Inbound Fault Recovery Table 4-1. Responsibility for Outbound Information Time Responsible Entity Before GPI_MT_TRANSFER_OUT_ Client program After GPI_MT_TRANSFER_OUT_ GPI service Inbound Fault Recovery During inbound processing, root objects have states. The states are similar to those for an executing process. Object states are described in Section 2, The GPI Library.
Planning Your Program Planning for Gateway Security Planning for Gateway Security When planning your program, you should also consider aspects related to gateway security.
Planning Your Program Supported Extensions Supported Extensions The GPI supports the 1988 extensions listed in Table 4-3. Listed are both the CCITT name and the DDL name of the associated GPI attribute. Note that the CommonName and TerminalType extensions correspond to CCITT extension-attributes. Table 4-3.
Planning Your Program Supported Extensions If the MTS component does not handle that extension, a nondelivery report is generated and the message is discarded. Figure 4-2. Object Representation of X.
Planning Your Program Unsupported Extensions As mentioned before, the two supported extensions that correspond to CCITT extensionattributes do not have criticality. You should not specify them as values of the MH-TCRITICAL-FOR- attributes. Unsupported Extensions A GPI gateway can also handle unsupported extensions. Unsupported extensions are not explicitly known to the GPI. Within the gateway, each unsupported extension is represented by an object of the MH-C-EXTENSION class (Figure 4-2).
5 Writing Your Program Before writing a GPI program, you should understand GPI procedures and how to use objects and attributes (see Section 2, The GPI Library, and Section 3, GPI Object Management). You should also have considered how to implement gateway fault recovery, security, and if necessary, multiple GPI sessions (Section 4, Planning Your Program). This section focuses on GPI program development. It shows how to use GPI procedures to construct a typical client program.
Writing Your Program Developing Program Structure The GPI portion of a client program consists of a sequence of calls to GPI environment management, object management, and message transfer procedures. The GPI procedures and supporting code are bound to the client program either at bind time or at run time.
Writing Your Program Developing Program Structure inbound processing, different object management procedures can be used at different times, corresponding to the two stages of inbound transfer. Following the first stage of inbound transfer, the root object transferred to GPI library memory space is unmodifiable; it can be inspected and copied but not changed. Following the final stage, the inbound object is modifiable.
Writing Your Program Developing Program Structure Figure 5-1.
Writing Your Program Managing the GPI Environment The descriptions of the parameters generally do not include a list of the minimum, maximum and default values. For detailed reference on each parameter, refer to the GPI Reference Manual. Note. For brevity, the status parameter has been omitted from the discussion of each GPI library procedure. For each GPI procedure, the status parameter returns a code that indicates the outcome of the procedure call.
Writing Your Program Initializing the GPI Environment max-string-length specifies the maximum length (in octets) of a string that the GPI is allowed to pass in an attribute descriptor. As described later, this relates to the type of data strings used with the GPI_OM_FETCH_ , GPI_OM_LIST_ , GPI_OM_EXAMINE_ , and GPI_OM_INSERT_ procedures. Setting Object Tree Table Size As mentioned in Section 3, GPI Object Management, an object tree is the internal format of a root object in GPI library memory space.
Writing Your Program Initializing the GPI Environment attribute contained within these subobjects (and used by your root object). If an attribute is multivalued, add an additional entry for each value present. Suppose, for this example, that six required and optional single-valued attributes are used in MH-C-MESSAGE-RD, and one multivalued attribute is used (for which there are three values). Further suppose that 23 single-valued attributes are used in MH-COR-NAME.
Writing Your Program Initializing the GPI Environment The memory required for each object tree depends on the max-table-entries and max-table-data parameters. The following formula applies: OT_memory = max-table-data + (28 x max-table-entries) where OT_memory is the amount of memory required per object tree.
Writing Your Program Initializing the GPI Environment Remember that, for each session required by the GPI process, a separate GIP is required. Therefore GIP_memory must be multiplied by num_sessions to determine the total amount of calculable GIP memory space needed. Note. Additional GIP memory is allocated internally for encoding and decoding messages.
Writing Your Program Initializing the GPI Environment It might be helpful to extend this example to include sample calculations for swap memory requirements. The formulas used in the following calculations were introduced in two previous subsections, “Determining GPI Library Memory Requirements” and “Determining GIP Memory Requirements.” In this example, suppose that the client process uses only one session and that no more than two objects will exist at the same time.
Writing Your Program Opening a Session Opening a Session You call the GPI_OPEN_ procedure to establish a session with the GPI service. A session is created by linking internal processes that allow communication between the client program and OSI/MHS MTA. Note. Because GPI_OPEN_ involves considerable internal processing, the time to complete GPI_OPEN_ might be significantly longer than that to complete other GPI procedures.
Writing Your Program Opening a Session Using the Gateway Password The gateway password protects the GPI gateway from unauthorized use. If a password has been configured for the GATEWAY object, you must specify the password in gateway-password; otherwise, the GPI service does not establish a session with the OSI/MHS MTA. Using the Gateway Instance Name The GPI service maintains but does not use the gateway instance name. You can use the name as a label for logging, tracing, or archiving purposes.
Writing Your Program Closing a Session gateway_password_length := 7, -- Length of gateway password mhs_mgr_name_length := 4; -- Length of mhs_mgr_name INT(32) environment_object; -- Local environment object id STRING gateway_name[0:31] := ["Gateway gateway_instance_name[0:31] := ["Instance mhs_mgr_name[0:3] := ["$ZG1"], gateway_password[0:6] := ["GATEWAY"]; "], "], Procedure call: status := GPI_OPEN_ ( gateway_name, gateway_instance_name, session, environment_object, mhs_mgr_name, mhs_mgr_name_length,
Writing Your Program Processing Outbound Information GPI_STATUS_ has several output parameters that return diagnostic codes. In addition, for certain errors, GPI_STATUS_ writes additional diagnostic information to an information buffer. Details on GPI_STATUS_ are provided in Section 6, Recovering From Errors. Processing Outbound Information After a GPI session has been established, the client program can do outbound and inbound processing.
Writing Your Program Building a Root Object Figure 5-2.
Writing Your Program Building a Root Object a superobject (on any level), you must first copy that object, so that the copy has a new object identifier. Note. In addition to rules listed above, there is one limitation on use of the GPI library memory segment: You can have no more than 15 root objects in the GPI library memory at the same time, regardless of the number of sessions (there is no limit on the number of objects that are not root objects).
Writing Your Program Building a Root Object The following subsections describe three subtasks of building a root object: • • • Creating an object (using GPI_OM_CREATE_ ) Inserting an attribute value (using GPI_OM_INSERT_ ) Writing a long string to an attribute value (using GPI_OM_WRITE_ ) Creating an Object You call the GPI_OM_CREATE_ procedure to create a new object of a specified class. GPI_OM_CREATE_ causes the GPI service to allocate resources required to represent the object.
Writing Your Program Building a Root Object Creating an Object With Defaults If you set initialize to OM-TRUE, the object is created and filled with default firstlevel attributes. The default attributes consist of all required and optional attributes that have initial values (the initial values are used). The required and optional attributes for each object class, and their initial values, are listed in the GPI Reference Manual.
Writing Your Program Building a Root Object INT(32) object_id, root_id, -- ID of new object -- ID of root object to -- which new object is to -- be associated initialize := OM_TRUE; -- Create object with defaults Procedure call: status := GPI_OM_CREATE_ ( class, initialize, object_id, root_id); Inserting an Attribute Value You call the GPI_OM_INSERT_ procedure to insert attribute values into an object.
Writing Your Program Building a Root Object can occur, for example, if an attribute was inserted previously or was initialized when the object was created. If the syntax of a value is OM-S-OBJECT, the value is the object identifier of the subobject you are inserting as an attribute.
Writing Your Program Building a Root Object Figure 5-3.
Writing Your Program descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.enumeration Building a Root Object := MH_T_BUILTIN_EITS; := OM_S_ENUMERATION; := MH_BE_IA5_TEXT ; Procedure call: status := GPI_OM_INSERT_ ( object_id, value_position, descriptor_list, descriptor_count); Writing a Long String to an Attribute Value You call the GPI_OM_WRITE_ procedure to write a segment of a long string to a specific value of a multivalued or single-valued attribute.
Writing Your Program Building a Root Object string-offset, on input, specifies whether you are inserting a new value or appending to an existing value. On output, string-offset is the offset (in octets) after the last string segment written. You can use the returned string offset as the starting position in the next GPI_OM_WRITE_ call. Note. The string offset cannot exceed the current length of the existing string value.
Writing Your Program Building a Root Object of string data. As shown, 20 is specified for string-offset, indicating GPI_OM_WRITE_ will add to the end of this string. An element-number of 10 is specified, indicating the string to be written is 10 octets. The buffer that contains the string to be written by GPI_OM_WRITE_ is called Buffer_Y. After the call, the string buffer for value 0 of attribute A is shown with the additional 10 octets.
Writing Your Program Transferring Out a Root Object syntax := OM_S_IA5_STRING; -- Syntax of string segment INT(32) object_id, -- ID of object that contains -- attribute to which string -- segment is written value_position := IGNORED_FOR_SINGLE_VALUED_ATT, element_number := 35D, -- Length of segment string_offset := ZGPI_NEW_VALUE; -- Starting point STRING .EXT data_string[0:79]; data_string ':=' "This is the content of the message.
Writing Your Program Transferring Out a Root Object the call to GPI_MT_TRANSFER_OUT_ fails. A subsequent call to GPI_STATUS_ indicates the specific cause of the failure. Note. The time to complete GPI_MT_TRANSFER_OUT_ is proportional to the size and complexity of the root object being transferred.
Writing Your Program Transferring Out a Root Object STRING local_identifier[0:31]; --String that uniquely -- identifies the outbound -- root object Procedure call: status := GPI_MT_TRANSFER_OUT_ (session, object_id, local_identifier, local_identifier_length, retain); Figure 5-7.
Writing Your Program Processing Inbound Information Processing Inbound Information The objective of inbound processing is to transfer in and retrieve information from an inbound root object. The client can also choose to copy the root object or edit its content. As described previously, transfer-in occurs in two stages: a starting stage and a finishing stage. Following the first stage, the root object is unmodifiable; it can be inspected and copied but not changed.
Writing Your Program Initiating Transfer-in of a Root Object Parameters for GPI_MT_WAIT_ are: session (input) interval (input) available (output) session specifies the identifier of the session that is monitoring the input queue. interval specifies the maximum interval of time (in 0.01-second units) that this procedure is to wait for an unreserved root object to be located on the input queue. The value can be as follows: = -1 Wait indefinitely for an unreserved object.
Writing Your Program Initiating Transfer-in of a Root Object Procedure call: status := GPI_MT_WAIT_ ( session, interval, available); Starting Transfer of an Inbound Root Object You call the GPI_MT_START_TRANSFER_IN_ procedure to start the inbound transfer. The call reserves a root object on the GPI service input queue and puts a copy of the object in the GPI library memory space. As the copy passes through the GIP, it is decoded into a form suitable for manipulation by GPI procedures.
Writing Your Program Retrieving Information From a Root Object encoded specifies whether an encoded or decoded object is returned. If the parameter is not present, a value of OM-FALSE is assumed, and the returned object will be a message, probe, or report in its fully decoded instantiation. Note.
Writing Your Program • • Retrieving Information From a Root Object Inspecting values of a multivalued attribute (using GPI_OM_LIST_ ) Reading a long string from an attribute value (using GPI_OM_READ_ ) The sequence and nature of these tasks varies, depending on the client’s specific objectives. Table 5-3 shows a typical example. Table 5-3.
Writing Your Program Retrieving Information From a Root Object descriptor-list-in is a list of descriptors specifying the types of attributes you want to fetch. Each descriptor must specify an attribute type; the syntax and value fields are ignored. descriptor-count specifies the number of descriptors you are supplying. descriptor-list-out is a buffer in your program’s memory space to which you want the descriptors returned.
Writing Your Program Retrieving Information From a Root Object Fetching String Values of Single-Valued Attributes The elements of an attribute value that has a syntax of OM-S-xxx-STRING are returned in the string buffer you specify. The starting address of each value is returned in the OM-S-string elements field of the descriptor value field for that attribute. For details on descriptor fields, refer to the GPI Reference Manual.
Writing Your Program Retrieving Information From a Root Object Figure 5-9.
Writing Your Program Retrieving Information From a Root Object Example: Inspecting an Object for Specific Attribute Types The following TAL example shows a call to GPI_OM_FETCH_ . The call is designed to inspect the class attribute of an object to determine its type.
Writing Your Program Retrieving Information From a Root Object Parameters for GPI_OM_EXAMINE_ are: object (input) values (input) attribute-position (input) maximum-number (input) descriptor-list (output) total-number (output) actual-number (output; optional) string-buffer (output; optional) string-buffer-length (input; optional) actual-string-length (output; optional) total-string-length (output; optional) object specifies the identifier of the object to be examined.
Writing Your Program Retrieving Information From a Root Object string-buffer-length specifies the maximum number of octets of string data that string-buffer can contain. The minimum value you can specify is 0. You must specify this parameter if you specify string-buffer. actual-string-length is the actual number of octets of string data returned. If the procedure is not successful, the parameter is unchanged.
Writing Your Program Retrieving Information From a Root Object If you detect either of these situations, you can retrieve the string by making another procedure call. To retrieve a long string, call the GPI_OM_READ_ procedure. To retrieve other strings, call GPI_OM_EXAMINE_ again and specify a larger buffer (string-buffer-length) or examine only one attribute by specifying its attribute position and a maximum-number value of 1.
Writing Your Program Retrieving Information From a Root Object After the call, a value of 18 is returned as the total number, indicating there are eighteen attributes in object X. A value of 4 is returned as actual-number, indicating four descriptors were returned. descriptor-list contains descriptors for the first four attributes examined. The first descriptor is for the class attribute, which is always at attribute position 0. The second descriptor is for attribute A, which represents an object.
Writing Your Program Retrieving Information From a Root Object Procedure call: status := GPI_OM_EXAMINE_ (object_id, values, attribute_position, maximum_number, descriptor_list, total_number, actual_number, string_buffer, string_buffer_length, actual_string_length, total_string_length); Inspecting Values of a Multivalued Attribute You call the GPI_OM_LIST_ procedure to identify the values of a multivalued attribute.
Writing Your Program Retrieving Information From a Root Object descriptor-list is a buffer in your program’s memory space to which you want the descriptors returned. The area must be large enough to contain the number of descriptors specified by maximum-number. The descriptors are returned in the order in which the values appear in the attribute. If the procedure is not successful or the value of maximum-number is 0, the buffer is unchanged. total-number is the total number of values in the attribute.
Writing Your Program • • Retrieving Information From a Root Object Returns the length of the value in the string-length field of the descriptor value field for the attribute Returns OM-ELEMENTS-UNSPECIFIED in the string-elements field If you detect either of these situations, you can retrieve the string by making another procedure call. To retrieve a long string, call the GPI_OM_READ_ procedure. To retrieve other strings, call GPI_OM_LIST_ again and specify a larger buffer (string-buffer-length).
Writing Your Program Retrieving Information From a Root Object After the call, the descriptor list is returned with the values 1, 2, and 3 of attribute type C. As shown in this example, these values contain a total of “xx” octets of short string data, which is placed in string-buffer. If the values had contained long strings, you would need to use the GPI_OM_READ_ procedure to read them. Example: Inspecting Values of a Multivalued Attribute The following TAL example shows a call to GPI_OM_LIST_ .
Writing Your Program Retrieving Information From a Root Object Reading a Long String From an Attribute Value You call the GPI_OM_READ_ procedure to read a segment of a long string from a specific value of a multivalued or single-valued attribute. A segment is a portion of a string made up of zero or more contiguous octets. You call this procedure as many times as needed to read all segments of the value.
Writing Your Program Retrieving Information From a Root Object data-string specifies a buffer in your program’s memory space to which you want the segment returned. The buffer must be long enough to contain the number of octets specified by maximum-number. If the procedure call is not successful or the value of maximum-number is 0, the buffer is unchanged. actual-number returns the actual number of octets read. If the procedure call is not successful, the parameter is unchanged.
Writing Your Program Finishing Transfer-in of a Root Object Example: Reading a Long String From an Attribute Value The following TAL example shows a call to GPI_OM_READ_ .
Writing Your Program Finishing Transfer-in of a Root Object Figure 5-13. Using GPI_MT_FINISH_TRANSFER_IN_ GPI Library Memory Segment Input Queue OBJECT Attribute Attribute Attribute Object is: 1. now modifiable or 2. deleted Message, Probe, or Report Object is: 1. now unreserved or 2. archived or 3. deleted or 4. transferred CDT 513.
Writing Your Program Finishing Transfer-in of a Root Object all specifies whether you want to change the state of all currently reserved objects or only the object specified in the object parameter. Note. If you specify OM-TRUE for all, objects not processed before an error condition occurs remain as reserved root objects on the input queue. Objects processed before the error occurs are removed and become the responsibility of the client.
Writing Your Program Editing a Root Object Data declarations: INT status, session; -- STATUS code -- ID of session INT(32) object_id, retain := OM_FALSE, all := OM_FALSE, remove := MH_REMOVE; ----- ID of inbound object Delete root object in memory Finish only this root object Delete root object on queue Procedure call: status := GPI_MT_FINISH_TRANSFER_IN_ ( session, object_id, retain, all, remove); Editing a Root Object After a successful call to GPI_MT_FINISH_TRANSFER_IN_ , a root object retained i
Writing Your Program Editing a Root Object Parameters for GPI_OM_REMOVE_ are: object (input) attribute-type (input) value-position (input) maximum-number (input) total-number (output) object specifies the identifier of the object whose attribute values you want to remove. attribute-type specifies the type of the attribute whose values you want to remove. value-position specifies the position within the attribute of the first value you want to remove.
Writing Your Program Editing a Root Object Figure 5-14.
Writing Your Program INT(32) object_id, value_position := 0D, maximum_number := 1D, total_number; Editing a Root Object ---------- ID of object which contains the attribute Position of the first value to be removed Maximum number of values to be removed Total number of values in object prior to this remove Procedure call: status := GPI_OM_REMOVE_ ( object_id, attribute_type, value_position, maximum_number, total_number); Deleting an Object You call the GPI_OM_DELETE_ procedure to delete an object.
Writing Your Program Editing a Root Object Copying an Object You call the GPI_OM_COPY_ procedure to create a new object that is an exact but independent copy of a specified object. The new object includes all objects contained in the object you are copying. The copied object is identical to the original, except that it has a different object identifier. The unique object identifier makes it possible to insert the copy in the same root object as the original.
Writing Your Program Editing a Root Object Procedure call: status := GPI_OM_COPY_ (original_id, copy_id, root_id); OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 5- 55
Writing Your Program Editing a Root Object OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 5- 56
6 Recovering From Errors The GPI provides features to detect and diagnose errors that occur during GPI procedure calls. Using these features, a client program can quickly recover from most GPI errors. This section describes the GPI error-checking and diagnostic features. It also provides some guidelines for error recovery.
Recovering From Errors Using the Status Parameter The specific error code returned depends on: • • The GPI procedure that failed The type of failure Note. Within XAPIA specifications, the literal for warning is OM-RC-TEMPORARY-ERROR. For clarity, the GPI uses the more explicit ZGPI-RC-WARNING. For a complete listing of all GPI status codes, refer to the GPI Reference Manual. The typical practice is to call GPI_STATUS_ immediately after an error code is returned in the status parameter.
Recovering From Errors Using the GPI_STATUS_ Procedure Using the GPI_STATUS_ Procedure The GPI_STATUS_ procedure is used to diagnose a failed GPI procedure call. GPI_STATUS_ has several output parameters that return diagnostic codes. In addition, for certain errors, GPI_STATUS_ writes additional information to an information buffer. You can inspect the buffer programmatically, as described later in this section.
Recovering From Errors Using the GPI_STATUS_ Procedure error-source indicates what low-level function within a GPI procedure failed. Note. error-qualifier and error-source are provided for use by Compaq service representatives. info-buffer is the name of the buffer to which you want additional error information returned. You must include this parameter if you specify a value greater than 0 for info-buffer-length. If you specify 0 for info-buffer-length, the buffer remains unchanged.
Recovering From Errors Using the GPI_STATUS_ Procedure information buffer has contents, the procedure calls print_info_data to display buffer contents. The print_info_data procedure is listed in full later in this section. Note. Several print macros are used in show_gpi_status to facilitate output of information to the user terminal. The DEFINE statements for these macros are listed after the listing for show_gpi_status.
Recovering From Errors Using the GPI_STATUS_ Procedure ---------------------------------------------------------------------------- Function Name: show_gpi_status ----- Arguments: status_context IN ----- Description: This function calls GPI_STATUS and prints status --information to the screen. It is called if --a warning or an error is detected. It shows --detailed information about the warning or error.
Recovering From Errors printfd (" printfd (" printfd (" printfd (" printfd (" printf (" Using the GPI_STATUS_ Procedure Error class: Primary code: Secondary code: Qualifier code: Error source: Info - buffer:"); ", ", ", ", ", error_class); primary_code); secondary_code); error_qualifier); error_source); ------------------------------------------------------------------------------------------------- Test Information Buffer -------------------------------------------------------------------------------
Recovering From Errors DEFINE Primary and Secondary Codes printfd( x,y ) = BEGIN outline ':=' x -> @outptr; CALL NUMOUT (tempstr, y, 10 , 5); outptr ':=' tempstr FOR 5 -> @outptr; outlen := $INT(@outptr - @outline); CALL WRITEX ( output_fn , outline , outlen ); END #; -- Print one long integer 'y' at the end of the string 'x': -- i.e.
Recovering From Errors Information Buffer Table 6-1.
Recovering From Errors Information Buffer Figure 6-3. Information Buffer Parameters Information Buffer Error Information pointer info_buffer info_buffer_length actual_info_length total_info_length CDT 603.CDD If total-info-length exceeds info-buffer-length, the error information is truncated. To read all the available information, you must call GPI_STATUS_ again, this time with a value of info-buffer-length that matches or exceeds totalinfo-length. Note.
Recovering From Errors Information Buffer Each of the other four structures also has the 32-bit identifier and the subordinate data structure. However, each of the other four subordinate structures contains different data fields. For additional details on the make-up of each structure, refer to the GPI Reference Manual. The five structure types relate to different errors. ZGPI-INFO-1 and ZGPI-INFO-2 relate to client problems.
Recovering From Errors Information Buffer Figure 6-5.
Recovering From Errors Information Buffer Figure 6-6. Sequence for Reading the Information Buffer 1 Pointer at buffer_address. ZGPI-Info-5 identified and read. Unread info = 54 bytes. Information Buffer 3 2 Pointer at buffer_address + 20 bytes. ZGPI-Info-1 identified and read. Unread info = 16 bytes. Information Buffer ZGPI-Info-5 (20 bytes) ZGPI-Info-5 (20 bytes) ZGPI-Info-1 (40 bytes) ZGPI-Info-1 (40 bytes) ZGPI-Info-3 (12 bytes) ZGPI-Info-3 (12 bytes) Pointer at buffer_address + 58 bytes.
Recovering From Errors Information Buffer ---------------------------------------------------------------------------- Function Name: print_info_buffer ----- Arguments: buffer_in IN --buffer_size OUT ----- Description: This function prints the info_buffer, which is --RETURNed by the GPI_STATUS_ function call. It --shows more detailed information about the error. ---------------------------------------------------------------------------PROC print_info_buffer ( buffer_in, buffer_size); STRING .
Recovering From Errors Information Buffer buffer_size := $LEN (ZGPI_INFO_2_DEF); printf (" Structure type: Dangling object "); printfld (" ROOT object identifier: ", struct_2_ptr.z_data.z_root_obj_id); printfd (" Object count: ", struct_2_ptr.z_data.z_obj_count); FOR counter := 0 TO struct_2_ptr.z_data.z_obj_count DO BEGIN printfld (" Object identifier: ", struct_2_ptr.z_data.z_obj_lst[counter].z_obj_id); printfd (" Object class: ", struct_2_ptr.z_data.z_obj_lst[counter].
Recovering From Errors Information Buffer Structures printfld (" Code 2: struct_5_ptr.z_data.z_code2); printfld (" Code 3: struct_5_ptr.z_data.z_code3); printfld (" Code 4: struct_5_ptr.z_data.z_code4); printfd (" Code 5: struct_5_ptr.z_data.z_code5); END; ", ", ", ", END; -- End print_info_buffer Information Buffer Structures The GPI_STATUS_ procedure returns data to a structure called the information buffer.
Recovering From Errors Information Buffer Structures ZGPI-ST-ERROR-ATTR (Value 10) A value of 10 for Z-STRUCT-TYPE indicates an error in the specification of an object’s attribute. This structure returns a description of the attribute descriptor that has caused an error. Z-STRUCT-TYPE CONSTANT ZGPI-ST-ERROR-ATTR DEFINITION ZGPI-INFO-1. STRUCTURE TYPE OBJECT ID OBJECT CLASS OBJECT TYPE ATTRIBUTE DESCRIPTOR: ATTRIBUTE TYPE ATTRIBUTE SYNTAX ATTRIBUTE VALUE STRING VALUE (CHAR) TYPE BINARY 32 VALUE 10.
Recovering From Errors Information Buffer Structures ATTRIBUTE VALUE The form of this field may vary with the syntax of the attribute. If the syntax is a boolean, enumeration, or integer, then the value is in the first four bytes of this field. If the syntax is an object, the object identifier is in the second four bytes of this field, and is of little value in debugging the problem, because it is an internal pointer.
Recovering From Errors Information Buffer Structures OBJECT LIST An array containing a list of the dangling objects. For each dangling object, the array contains Z-OBJ-ID and Z-OBJ-CLASS. OBJECT ID An internal pointer with little use in troubleshooting. OBJECT CLASS The class of the dangling object. This is the most useful information in ZGPI-INFO-2, because it identifies the class of the object which has not been attached correctly. For the literal definitions refer to the GPI DDL.
Recovering From Errors Information Buffer Structures CODE 4 This field contains the class of the error. All errors returned from the GIP in this format contain the class of the error. This is intended to aid application programmers in determining what general types of action may be taken to remedy the situation. It has the same meaning as the class returned as a GPI_STATUS parameter, except that it is being returned by an internal function.
Recovering From Errors Information Buffer Structures ZGPI-ST-INFO-5 (Value 50) This structure provides extended error information to be reported to your Compaq representative. This structure is returned when an internal decode or encode function has returned an error. Z-STRUCT-TYPE CONSTANT ZGPI-ST-INFO-5 DEFINITION ZGPI-INFO-5. STRUCTURE-TYPE CODE 1 CODE 2 CODE 3 CODE 4 CODE 5 TYPE BINARY 32 0000 0000 0000 0000 0000 0000 VALUE 50.
Recovering From Errors Recovering From a GIP Failure Recovering From a GIP Failure If a GIP fails while in session with a client process, the client eventually receives a status error code that indicates the current gateway session has been aborted. The error code is returned by the current or next called GPI procedure. When this occurs, it is the client’s responsibility to recover the aborted session. Typically, the client will re-establish the session by a call to GPI_OPEN_ .
Recovering From Errors Common GPI Errors GIP Not Started ZGPI-RC-NO-GIPS The returned value is 4012. At least one GIP process must be running on the OSI/MHS subsystem for a GPI_OPEN_ procedure call to succeed. When the client issues a GPI_OPEN_ call and no GIP processes have yet been started, the GPI returns the error code 4012, ZGPI-RCNO-GIPS. GPI Not Initialized ZGPI-RC-USESEGMENT-ERROR The returned value is 2504.
Recovering From Errors Common GPI Errors the GPI returns error code 26, OM-RC-WRONG-VALUE-LENGTH. The secondary code contains the attribute type. MHS Manager Communication Problem If GPI_OPEN_ returns an SPI or SCP-related error then the problem concerns communications between the GPI library and the MHSMGR. The MGSMGR may not be available, may not be compatible with the GPI release, or the GIP may not be configured.
Recovering From Errors Common GPI Errors An example of a TRANSFER error code is 59535 decimal (E88F in hexadecimal, equal to -6001 in unsigned decimal). This common error (returned from the Entry Manager) sometimes indicates that the ADMIN queue is empty. Normally, a Message Relay process (MRP) will register itself by placing an administration entry on the ADMIN queue. The GIP will read this administration entry in order to establish communication with the MRP.
Recovering From Errors Common GPI Errors OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 6- 26
A TAL Program Example ------------------------------------------------------------------------------- Description: This program shows how a client program, operating -- through a NORMAL type GPI gateway, calls each GPI procedure. It opens a -- session, creates a root object, transfers the root object out, transfers -- the root object back in, shows values of root object attributes, then -- closes the session.
TAL Program Example -The printing of these attributes and objects is handled by two -procedures: print_attributes and print_object. Each takes as input -an array containing the attribute list to be printed. Again, the -program assumes certain attributes are present in the inbound root -object. ---------------------------------------------------------------------------- Note. A sample of program output appears at the end of this appendix.
TAL Program Example DEFINE printfx( x,y,z ) = BEGIN outline ':=' x -> @outptr; CALL print_hex (z,y,outptr); @outptr := @outptr[y]; outlen := $INT(@outptr - @outline); CALL WRITEX ( output_fn , outline , outlen ); END #; --------------------------------- Literals --------------------------------literal FIRST= 1 ; literal SECOND = 2 ; -- Flag for the multivalued attribute -- Flag for the multivalued attribute literal MAX_DESCRIPTORS = 20; -- Maximum number of elements in the -- descriptor list literal
TAL Program Example ?nolist, source GPIExt ?list -- Include the Guardian procedure prototype declarations ?nolist, source extdecs( abend ? , close ? , debug ? , myterm ? , numout ? , open ? , read ? , writex ? ) ?list ?page ---------------------------------------------------------------------------- Function Name: gpiex_init ----- Arguments: none ----- Description: This procedure reads the startup message and opens --the output file.
TAL Program Example CALL CLOSE (receive); -- Open the out file CALL OPEN ( startup.output_file_name, output_fn ); IF <> THEN BEGIN CALL MYTERM ( startup.output_file_name ); CALL OPEN (startup.output_file_name,output_fn); outline ':=' "Output file open error.
TAL Program Example i := i + 1; buff[i] ':=' "-"; END; if t = 0 then t := 1; for s := 1 to t DO BEGIN a := num[t-s]; buff[s + i] := dec[a]; END; buff[s + i] := 0; width := s + i; return; END; ?page ---------------------------------------------------------------------------- Function Name: print_hex ----- Arguments: str hex input buffer pointer IN --len number of bytes to print IN --buff output buffer pointer IN/OUT ----- Description: This procedure reads bytes from str and prints the --hex characters for t
TAL Program Example ---- Description: This function prints the info_buffer, which is --returned by the GPI_STATUS_ function call. It --shows more detailed information about the error. ---------------------------------------------------------------------------PROC print_info_buffer ( buffer_in, buffer_size); STRING .EXT buffer_in; INT .buffer_size; BEGIN INT counter; -- Counter for the loop -- This redefinition allows us to use one pointer to access all the different -- info buffer structures. STRING .EXT .
TAL Program Example struct_2_ptr.z_data.z_obj_count); counter := 0 TO struct_2_ptr.z_data.z_obj_count DO BEGIN printfld (" Object identifier: ", struct_2_ptr.z_data.z_obj_lst[counter].z_obj_id); printfd (" Object class: ", struct_2_ptr.z_data.z_obj_lst[counter].z_obj_class); END; -- FOR -printf (" "); END FOR ELSE IF (struct_1_ptr.z_struct_type = ZGPI_ST_INFO_3) THEN BEGIN buffer_size := $LEN (ZGPI_INFO_3_DEF); printf (" Structure type: Structure 3"); printfd (" Code 1: ", struct_3_ptr.z_data.
TAL Program Example printfd (" Code 5: struct_5_ptr.z_data.z_code5); END; ", END; -- End print_info_buffer ?page ---------------------------------------------------------------------------- Function Name: show_gpi_status ----- Arguments: status_context IN ----- Description: This function calls GPI_STATUS and prints status --information to the screen. It is called if --a warning or an error is detected. It shows --detailed information about the warning or error.
TAL Program Example printfd (" END; printf (" printf (" printfd (" printfd (" printfd (" printfd (" printfd (" printfd (" printfd (" printfd (" printf (" WARNING from GPI_STATUS_! number: ", local_rc ); Error Information "); ================= "); Request type: ", request_type); Session: ", local_session); Client RETURN code: ", old_status); Error class: ", error_class); Primary code: ", primary_code); Secondary code: ", secondary_code); Qualifier code: ", error_qualifier); Error source: ", error_source
TAL Program Example -- Description: This procedure searches for the type in the --descriptor list and RETURNs the position of the --type. --------------------------------------------------------------------------INT PROC search_descriptor ( type, att_list, number ); INT type; -- Type to search for STRING .
TAL Program Example descriptor_list[2].type descriptor_list[2].syntax descriptor_list[2].value.boolean := MH_T_CONTENT_RETURN_REQUESTED; := OM_S_BOOLEAN; := OM_FALSE ; descriptor_list[3].type descriptor_list[3].syntax descriptor_list[3].value.integer := MH_T_CONTENT_TYPE; := OM_S_INTEGER; := MH_CTI_P2_1988 ; descriptor_list[4].type descriptor_list[4].syntax descriptor_list[4].value.boolean := MH_T_CONVERSION_PROHIBITED; := OM_S_BOOLEAN; := OM_FALSE ; descriptor_list[5].type descriptor_list[5].
TAL Program Example descriptor_list[0].type := MH_T_INFORMATION; descriptor_list[0].syntax := OM_S_OCTET_STRING; descriptor_list[0].value.z_string.length := 5D ; data_buf_in ':=' [%h04,%h03,%h00,%h00,%h00]; @descriptor_list[0].value.z_string.
TAL Program Example END; -- End build_and_insert_bilateral_obj ?page ---------------------------------------------------------------------------- Function Name: build_and_insert_ipmid_object ----- Arguments: root_id IN --object_id IN ----- Return: Return code from the function call ----- Description: This function creates the im_c_ipm_identifier object--with the initial value parameter set to FALSE. The --function then inserts all the required attributes --into the object.
TAL Program Example "object"); descriptor_count := 1D; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.object.padding descriptor_list[0].value.object.
TAL Program Example IF (( local_rc = OM_RC_SUCCESS ) or ( local_rc = ZGPI_RC_WARNING )) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Insert all the required attributes"); local_rc := GPI_OM_INSERT_ ( local_object, IGNORED_FOR_SINGLE_VALUED_ATT, descriptor_list, descriptor_count ); IF (( local_rc = OM_RC_SUCCESS ) or (local_rc = ZGPI_RC_WARNING)) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" "
TAL Program Example printf (" " & "Insert the object into the " & "IM_C_INTERPERSONAL_MESSAGE object"); descriptor_count := 1D; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.object.padding descriptor_list[0].value.object.
TAL Program Example descriptor_list[2].type descriptor_list[2].syntax descriptor_list[2].value.enumeration := IM_T_SENSITIVITY; := OM_S_ENUMERATION; := IM_NOT_SENSITIVE ; descriptor_list[3].type := IM_T_SUBJECT; descriptor_list[3].syntax := OM_S_TELETEX_STRING; descriptor_list[3].value.z_string.length := 10D ; data_buf_in ':=' "MY SUBJECT"; @descriptor_list[3].value.z_string.
TAL Program Example descriptor_list, descriptor_count); END; -- then END; -- then END; -- then END; -- then RETURN (local_rc); END; -- End build_and_insert_ipm_object ?page ---------------------------------------------------------------------------- Function Name: build_and_insert_trace_object ----- Arguments: root_id IN ----- Return: Return code from the function call ----- Description: This function creates the mh_c_external_trace_entry --with the initial value parameter set to FALSE.
TAL Program Example descriptor_list[3].syntax descriptor_list[3].value.enumeration := OM_S_ENUMERATION; := MH_AC_RELAYED ; ----------------------------------------------------------------------------WARNING!! --The MH_T_ARRIVAL_TIME should be set to the current time or --a time in the future to keep the message from being --non-delivered due to timeout of the message. The null value --below works since the message is being looped back to the --originator.
TAL Program Example END; -- then END; -- then RETURN (local_rc); END; -- End build_and_insert_trace_object ?page ---------------------------------------------------------------------------- Function Name: build_and_insert_mtsid_object ----- Arguments: root_id IN ----- Return: Return code from the function call ----- Description: This function creates the mh_c_mts_identifier --with the initial value parameter set to FALSE. The --function then inserts all the required attributes --into the object.
TAL Program Example IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Insert all required attributes"); local_rc := GPI_OM_INSERT_ ( local_object, IGNORED_FOR_SINGLE_VALUED_ATT, descriptor_list, descriptor_count); IF (( local_rc = OM_RC_SUCCESS ) or (local_rc = ZGPI_RC_WARNING)) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Insert the object into the root object"); descriptor_count := 1D; descriptor_list[0].
TAL Program Example OM_FALSE, -- Without defined initial -- values local_object, root_id, -- Root object ); -- Session not necessary IF (( local_rc = OM_RC_SUCCESS ) OR ( local_rc = ZGPI_RC_WARNING )) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Insert all required attributes"); local_rc := GPI_OM_INSERT_ ( local_object, IGNORED_FOR_SINGLE_VALUED_ATT, descriptor_list, descriptor_count); IF (( local_rc = OM_RC_SUCCESS ) OR (local_rc = ZGPI_RC_WARNI
TAL Program Example ---------------------------------------------------------------------- NOTE: The values below are hardcoded. We recommend using the --values passed back in the environment object returned from--the GPI_OPEN_ call. ---------------------------------------------------------------------STRUCT .EXT descriptor_list(OM_descriptor)[0:5]; @data_buf_in_ptr := @data_buf_in; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.z_string.length @descriptor_list[0].value.
TAL Program Example IF (( local_rc = OM_RC_SUCCESS ) OR (local_rc = ZGPI_RC_WARNING)) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Insert the object into the root object"); descriptor_count := 1D; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.object.padding descriptor_list[0].value.object.
TAL Program Example @descriptor_list[0].value.z_string.elements := @data_buf_in_ptr; data_buf_in_ptr ':=' "POSTMASTER1" -> @data_buf_in_ptr; descriptor_list[1].type descriptor_list[1].syntax descriptor_list[1].value.z_string.length @descriptor_list[1].value.z_string.elements data_buf_in_ptr ':=' "US" := := := := -> MH_T_COUNTRY_NAME; OM_S_PRINTABLE_STRING; 2D ; @data_buf_in_ptr; @data_buf_in_ptr; descriptor_list[2].type descriptor_list[2].syntax descriptor_list[2].value.z_string.
TAL Program Example printf (" " & "Insert the object into the MH_C_MESSAGE_RD object"); descriptor_count := 1D; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.object.padding descriptor_list[0].value.object.
TAL Program Example .EXT desc_list(OM_descriptor)[0:MAX_DESCRIPTORS]; -- This descriptorlist is used for the function call GPI_OM_EXAMINE. descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.enumeration := MH_T_EXPLICIT_CONVERSION; := OM_S_ENUMERATION; := MH_EC_NO_CONVERSION; descriptor_list[1].type descriptor_list[1].syntax descriptor_list[1].value.enumeration descriptor_list[2].type descriptor_list[2].syntax descriptor_list[2].value.boolean := := := := := := descriptor_list[3].
TAL Program Example descriptor_list[0].value.object.padding := 0D; descriptor_list[0].value.object.
TAL Program Example -- Build and insert the second rdorname_object local_rc := build_and_insert_rdorname_obj (root_id,local_object_2,SECOND); IF (( local_rc = OM_RC_SUCCESS ) OR ( local_rc = ZGPI_RC_WARNING )) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc); printf (" " & "Remove the attribute " & "MH_T_RECIPIENT_NUMBER"); local_rc := GPI_OM_REMOVE_ ( local_object_2, MH_T_RECIPIENT_NUMBER, -- Attribute type 0D, -- Value position 1D, -- Maximum number total_number)
TAL Program Example object := local_object_2; local_rc := GPI_OM_INSERT_ ( root_id, OM_POSITION_AT_END, descriptor_list, descriptor_count); END; -- then END; -- then END; -- then END; -- then END -- then ELSE printf (" MH_C_OR_NAME doesn't exist.
TAL Program Example BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Creating and inserting ROOT ATTRIBUTES"); local_rc := insert_root_attributes (root_id); -- Create and insert the bilateral information IF (( local_rc = OM_RC_SUCCESS ) OR (local_rc = ZGPI_RC_WARNING)) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); printf (" Object BILATERAL INFORMATION "); local_rc := build_and_insert_bilateral_obj (root_id); --
TAL Program Example printfd (" WARNING! number: ", local_rc ); printf (" Object OR NAME"); local_rc := build_and_insert_orname_object (root_id); -- Create and insert the recipient descriptor IF (( local_rc = ( local_rc = BEGIN IF ( local_rc printfd (" printf (" OM_RC_SUCCESS ) OR ZGPI_RC_WARNING )) THEN = ZGPI_RC_WARNING ) THEN WARNING! number: ", local_rc ); Object MESSAGE RD"); local_rc := build_and_insert_messagerd_obj (root_id); END; -- then END; -- then END; -- then END; -- then END; -- then END; --
TAL Program Example INT local_rc, len, exist; -- RETURN code from the function call -- The RETURN value from the stccpy function -- Position from the element in descriptor list INT(32) string_offset, string_length, actual_number, total_number; ----- String offset for GPI_OM_READ_ Length in octets of the string to read Actual number of octets Total number of octets INT counter_2, counter ; -- Counter for the loop -- Counter for the loop STRING .octet_pointer, .EXT data_string[0:STRING_BUFFER_LEN], .
TAL Program Example ) ; END; OM_S_TELETEX_STRING , OM_S_UTC_TIME_STRING , OM_S_IA5_STRING , OM_S_PRINTABLE_STRING -> BEGIN outline ':=' print_data[counter].text FOR 32 -> @outptr; -- Need to take care string length > 100 later outptr ':=' descriptor_list[exist].value.z_string.elements FOR $INT(descriptor_list[exist].value.z_string.length) -> @outptr ; CALL WRITEX ( output_fn , outline , $INT(@outptr - @outline) ) ; END; OM_S_INTEGER -> BEGIN outline ':=' print_data[counter].
TAL Program Example string_offset, --string_length, -data_string, -actual_number, --total_number ); --IF (( local_rc = ( local_rc = BEGIN IF ( local_rc printfd (" Offset of the start of the string to read Number of string to be read Buffer to contain the strings The actual number of octets read by this call Returns the total number of octets in this value OM_RC_SUCCESS ) OR ZGPI_RC_WARNING )) THEN = ZGPI_RC_WARNING ) THEN WARNING! number: ", local_rc ); outline ':=' print_data[counter].
TAL Program Example END -- then ELSE BEGIN CALL show_gpi_status (ZGPI_ANY); END; -- else END; -- else END -- then ELSE BEGIN outline ':=' " Attribute doesn't exist. Name: "-> @outptr; outptr ':=' print_data[counter].
TAL Program Example -- print string for the -- attributes STRING .EXT f_desc_list (OM_descriptor) ; -- Descriptor list for fetch STRING .
TAL Program Example END; -- End print_object ?page --------------------------------------------------------------------------- Function Name: print_message ----- Arguments: root_id IN ----- Return: Return code from the function call ----- Description: This function will print all the attributes in the --message that this program transfered in, under the --assumption that the received message is the same as--the one transfered out.
TAL Program Example print_arr[3].type print_arr[3].text print_arr[4].type print_arr[4].text print_arr[5].type print_arr[5].text print_arr[6].type print_arr[6].
TAL Program Example print_arr[1].type print_arr[2].type print_arr[3].type print_arr[0].text print_arr[1].text print_arr[2].text print_arr[3].
TAL Program Example max_print_def, print_arr, f_descriptor_list, descriptor_list_2, actual_number_2); -- Print external trace entry max_print_def := 5D; f_descriptor_list[0].type := MH_T_ADMD_NAME; f_descriptor_list[1].type := MH_T_COUNTRY_NAME; f_descriptor_list[2].type := MH_T_PRMD_IDENTIFIER; f_descriptor_list[3].type := MH_T_ACTION; f_descriptor_list[4].type := MH_T_ARRIVAL_TIME; print_arr[0].type := MH_T_ADMD_NAME; print_arr[1].type := MH_T_COUNTRY_NAME; print_arr[2].
TAL Program Example actual_number); -- Print or name max_print_def := 6D; f_descriptor_list[0].type f_descriptor_list[1].type f_descriptor_list[2].type f_descriptor_list[3].type f_descriptor_list[4].type f_descriptor_list[5].type print_arr[0].type print_arr[1].type print_arr[2].type print_arr[3].type print_arr[4].type print_arr[5].type print_arr[0].text print_arr[1].text print_arr[2].text print_arr[3].text print_arr[4].text print_arr[5].
TAL Program Example actual_number_2, string_buffer_2, STRING_BUFFER_LEN, actual_string_len_2, total_string_len_2 ); IF (( local_rc = OM_RC_SUCCESS ) OR ( local_rc = ZGPI_RC_WARNING )) THEN BEGIN IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ",local_rc ); max_print_def := 5D; print_arr[0].type := MH_T_EXPLICIT_CONVERSION; print_arr[1].type := MH_T_MTA_REPORT_REQUEST; print_arr[2].type := MH_T_MTA_RESPONSIBILITY; print_arr[3].type := MH_T_ORIGINATOR_REPORT_REQUEST; print_arr[4].
TAL Program Example BEGIN printf (" END; -- else END; -- then MH_T_CONTENT dosen't exist"); RETURN (local_rc); END; -- End print_message ?page ---------------------------------------------------------------------------- Function Name: print_root_object ----- Arguments: root_id IN ----- Return: Return code from the function call ----- Description: This function uses GPI_OM_FETCH_ to determine the --class of the received root object.
TAL Program Example IF ( local_rc = ZGPI_RC_WARNING ) THEN printfd (" WARNING! number: ", local_rc ); message_class := descriptor_list_out[0].value.integer; printf (" "); -- Since TAL needs 16-bit integers for case statements, we are forced -- to convert message_class to a 16-bit integer, possibly losing -- information.
TAL Program Example local_identifier[0:31]; -- Local identifier string that uniquely -- identifies the transferred out object INT gateway_password_len := 7, -- Length of the gateway password mhs_mgr_name_len := 4; -- Length of the mhs_mgr_name -- Call the initialize procedure to set up output CALL gpiex_init; printf (" printf (" printf (" *******************************"); * Program example is starting *"); *******************************"); -- Initialize the GPI system printf (" Call GPI_INITIALIZE_"
TAL Program Example CALL show_gpi_status (ZGPI_ANY); END; -- Transfer out the root object printf (" Call GPI_MT_TRANSFER_OUT_"); rc := GPI_MT_TRANSFER_OUT_ ( session, outbound_object, local_identifier, local_identifier_len, OM_FALSE, -- Retain ); IF (( rc = OM_RC_SUCCESS ) OR ( rc = ZGPI_RC_WARNING )) THEN BEGIN printf (" --> was successful! "); IF ( rc = ZGPI_RC_WARNING ) THEN BEGIN printf (" *********** WARNING! **********"); CALL show_gpi_status (ZGPI_ANY); END; -- Wait for the root object printf (" C
TAL Program Example printf (" Call SHOW_MESSAGE "); rc := print_root_object ( inbound_object ); IF (( rc = OM_RC_SUCCESS ) OR ( rc = ZGPI_RC_WARNING )) THEN BEGIN printf (" SHOW_MESSAGE "was successful! "); --> " & IF ( rc = ZGPI_RC_WARNING ) THEN BEGIN printf (" *********** WARNING! "); printf ("**********"); CALL show_gpi_status (ZGPI_ANY); END; -- End transfer in printf (" Call GPI_MT_FINISH_TRANSFER_IN_"); rc := GPI_MT_FINISH_TRANSFER_IN_ ( session, inbound_object, OM_FALSE, -- Delete this msg O
TAL Program Example ELSE BEGIN printfd (" GPI_MT_WAIT failed! Error: ", rc ); CALL show_gpi_status (ZGPI_ANY); END; -- else END -- then ELSE BEGIN printfd (" GPI_MT_TRANSFER_OUT failed! " & "Error: ", rc ); CALL show_gpi_status (ZGPI_ANY); END; -- else END -- then ELSE BEGIN printfd (" BUILD_ROOT_OBJECT failed! Error: ", rc ); CALL show_gpi_status (ZGPI_ANY); END; -- else -- Close the session printf (" Call GPI_CLOSE_ "); rc := GPI_CLOSE_ (session); IF (( rc = OM_RC_SUCCESS ) OR ( rc = ZGPI_RC_WARNING ))
TAL Program Example Call Call Call Call Creating and inserting ROOT ATTRIBUTES Object BILATERAL INFORMATION Create the object Remove the attribute PRMD_IDENTIFIER Insert all the required attributes Insert the object into the root object Object INTERPERSONAL MESSAGE Create the object Insert all the required attributes Object IA5 TEXT BODY PART Create the object Insert all the required attributes Use GPI_OM_WRITE to write the first line Use GPI_OM_WRITE_ to write the second line Insert the object into the I
TAL Program Example The received object is a message Number of attributes: 15 Alternate Recip Allowed: 0 Content Identifier: Content Return Request: 0 Content Type: 22 Conversion Prohibited: 0 Disclosure Allowed: 0 Priority: 0 Bilateral Information Admd Name: POSTMASTER1 Country Name: US Information: 04 03 Interpersonal Message Auto Forward: 0 Importance: 1 Sensitivity: 0 Subject: MY SUBJECT IA5 Text Body Part Repertoire: 5 Text: This is the content of the message. This is the second line.
TAL Program Example Prmd Name: DEVELOPMENT Organization Name: MTA1 Organization Unit Name:GWUSERS Surname: UAGW12 SHOW_MESSAGE --> was successful! Call GPI_MT_FINISH_TRANSFER_IN_ --> was successful! Call GPI_CLOSE_ --> was successful! ************************************ * Programming example is finishing * ************************************ OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 A -53
TAL Program Example OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 A -54
B C Program Example /*************************************************************************** * * Description:This program shows how a client program, operating through * a NORMAL type GPI gateway, calls each GPI procedure. It opens a session, * creates a root object, transfers the root object out, transfers the root * object back in, shows values of root object attributes, then closes the * session.
C Program Example * object. ***************************************************************************/ Note. A sample of program output appears at the end of this appendix.
C Program Example unsigned long read_object_id; /* This object identifer is used for calling /* GPI_OM_READ_. It contains the object identifer /* under which the attribute to be read is found. */ */ */ #pragma page /**************************************************************************/ /* Function Name: print_info_buffer */ /* */ /* Arguments: buffer_in IN */ /* buffer_size OUT */ /* */ /* Description: This function prints the info_buffer, which is */ /* returned by the GPI_STATUS_ function call.
C Program Example buffer_in->info_struc_2.z_data.z_obj_count); for ( counter = 0; counter < buffer_in->info_struc_2.z_data.z_obj_count; counter++ ) { printf (" Object identifier: %ld\n", buffer_in->info_struc_2.z_data.z_obj_lst[counter].z_obj_id); printf (" Object class: %d\n\n", buffer_in->info_struc_2.z_data.z_obj_lst[counter].
C Program Example /* information to the screen. It is called if */ /* a warning or an error is detected. It shows detailed */ /* information about the warning or error.
C Program Example total_info_len); /* access info buffer memory only if a buffer was provided */ if ( actual_info_len > 0 ) { buffer_adress = &buffer; do { print_info_buffer (buffer_adress,&structure_size); actual_info_len = actual_info_len - structure_size; if ( actual_info_len > 0 ) { /* Add calculation for second buffer */ actual_info_len = 0; } /* if */ } while ( actual_info_len > 0 ); }; /* if */ if ( total_info_len > ZGPI_MAX_STATUS_BUF_LEN ) { printf (" The size of the info buffer is too small \n");
C Program Example while (counter < number ) { if ( att_list[counter].
C Program Example /* Return: Return code from the function call */ /* */ /* Description: This function creates the mh_c_bilateral_information */ /* object with the initial value parameter set to TRUE. */ /* This will cause the object to be populated with the */ /* attributes that have default values. One of these */ /* attributes, the PRMD_IDENTIFER, is then removed */ /* because it is not wanted in our message.
C Program Example */ local_rc = GPI_OM_INSERT_ ( local_object, IGNORED_FOR_SINGLE_VALUED_ATT, descriptor_list, descriptor_count); if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" "); printf ("Insert the object into the root object\n"); descriptor_count = 1; descriptor_list[0].type = MH_T_BILATERAL_INFORMATION; descriptor_list[0].syntax = OM_S_OBJECT; descriptor_list[0].value.object.
C Program Example IM_T_USER_RELATIVE_IDENTIFIER,OM_S_PRINTABLE_STRING,{ 10 ,"MY-USER-ID" } }; printf (" Create the object\n"); local_rc = GPI_OM_CREATE_ ( IM_C_IPM_IDENTIFIER,/* Class of the object OM_FALSE, /* Without defined initial /* values &local_object, root_id, /* Root object identifier ); /* Session not necessary */ */ */ */ */ if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Inser
C Program Example /* into the object. It then inserts the object into */ /* the im_c_interpersonal_message object.
C Program Example string_offset = ZGPI_NEW_VALUE; local_rc = GPI_OM_WRITE_ ( local_object, IM_T_TEXT, /* Attribute type IGNORED_FOR_SINGLE_VALUED_ATT, &string_offset, /* String offset data_string, /* Data string element_number, /* Element number OM_S_IA5_STRING ); /* Syntax */ */ */ */ */ if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" "); printf ("Use GPI_OM_WRITE_ to write the second li
C Program Example #pragma page /**************************************************************************/ /* Function Name: build_and_insert_ipm_object */ /* */ /* Arguments: root_id IN */ /* */ /* Return: Return code from the function call */ /* */ /* Description: This function creates the im_c_interpersonal_message */ /* with the initial value parameter set to FALSE. The */ /* function then inserts all the required attributes */ /* into the object.
C Program Example if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Object IPM IDENTIFIER\n"); local_rc = build_and_insert_ipmid_object (root_id,local_object); if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" "); printf ("Insert the object into the root object\n"); descriptor_cou
C Program Example descriptor_list[] = { MH_T_ADMD_NAME, OM_S_PRINTABLE_STRING,{ 11 , "POSTMASTER1" MH_T_COUNTRY_NAME, MH_T_PRMD_IDENTIFIER, OM_S_PRINTABLE_STRING,{ 2 , "US" }, OM_S_PRINTABLE_STRING,{ 11 , "DEVELOPMENT" MH_T_ACTION, OM_S_ENUMERATION, }, }, { MH_AC_RELAYED }, /********************************************************************/ /* WARNING!! */ /* The MH_T_ARRIVAL_TIME should be set to the current time */ /* or a time in the future to keep the message from being */ /* non-delivered du
C Program Example descriptor_list, descriptor_count); } /* if */ } /* if */ return (local_rc); } /* build_and_insert_trace_object */ #pragma page /**************************************************************************/ /* Function Name: build_and_insert_mtsid_object */ /* */ /* Arguments: root_id IN */ /* */ /* Return: Return code from the function call */ /* */ /* Description: This function creates the mh_c_mts_identifier */ /* with the initial value parameter set to FALSE.
C Program Example descriptor_list, descriptor_count); if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Insert the object into the root object\n"); descriptor_count = 1; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.object.padding descriptor_list[0].value.object.
C Program Example if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Insert all required attributes\n"); local_rc = GPI_OM_INSERT_ ( local_object, IGNORED_FOR_SINGLE_VALUED_ATT, descriptor_list, descriptor_count); if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Insert the object in
C Program Example OM_descriptor descriptor_list[] = { MH_T_ADMD_NAME, OM_S_PRINTABLE_STRING,{ 11 , MH_T_COUNTRY_NAME, OM_S_PRINTABLE_STRING,{ 2 , MH_T_PRMD_NAME, OM_S_PRINTABLE_STRING,{ 11 , MH_T_ORGANIZATION_NAME, OM_S_PRINTABLE_STRING,{ 4 , MH_T_ORGANIZATIONAL_UNIT_NME_1,OM_S_PRINTABLE_STRING,{ MH_T_SURNAME, OM_S_PRINTABLE_STRING,{ }; printf (" "POSTMASTER1" "US" }, "DEVELOPMENT" "MTA1" }, 7 , "GWUSERS" 6 , "UAGW11" }, }, }, } Create \n"); local_rc = GPI_OM_CREATE_ ( MH_C_OR_NAME, OM_FALSE, &local_ob
C Program Example /* */ /* Description: This function creates the mh_c_or_name */ /* with the initial value parameter set to FALSE. The */ /* function then inserts all the required attributes */ /* into the object. It then inserts the object into */ /* the mh_c_message_rd object. */ /* */ /* NOTE: This function is called twice: once for each */ /* of the multivalued attributes */ /* (mh-c-message-rd).
C Program Example printf (" WARNING! number: %d \n", local_rc ); printf (" "); printf ("Insert the object into the MH_C_MESSAGE_RD object\n"); descriptor_count = 1; descriptor_list[0].type descriptor_list[0].syntax descriptor_list[0].value.object.padding descriptor_list[0].value.object.
C Program Example local_object_2; /* Local object identifier */ OM_descriptor descriptor_list[] = { MH_T_EXPLICIT_CONVERSION, OM_S_ENUMERATION,{ MH_EC_NO_CONVERSION }, MH_T_MTA_REPORT_REQUEST, OM_S_ENUMERATION,{ MH_RQ_ALWAYS}, MH_T_MTA_RESPONSIBILITY, OM_S_BOOLEAN, { OM_TRUE }, MH_T_ORIGINATOR_REPORT_REQUEST,OM_S_ENUMERATION,{ MH_RQ_ALWAYS }, MH_T_RECIPIENT_NUMBER, OM_S_INTEGER, { 1 } }, desc_list[MAX_DESCRIPTORS]; /* This descriptorlist is used for */ /* the function call GPI_OM_EXAMINE.
C Program Example ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Copy the object \n"); local_rc = GPI_OM_COPY_ ( local_object, /* /* &local_object_2, root_id, ); /* /* Original object */ identifier */ Session not necessary */ */ if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" "); printf ("Examine the object i
C Program Example if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc); printf (" "); printf ("Remove the attribute "); printf ("MH_T_RECIPIENT_NUMBER\n"); local_rc = GPI_OM_REMOVE_ ( local_object_2, MH_T_RECIPIENT_NUMBER, /* Attribute type */ 0, /* Value position */ 1, /* Maximum number */ &total_number); if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING
C Program Example ( root_id, /* Root object */ /* identifier */ OM_POSITION_AT_END, descriptor_list, descriptor_count); } /* if */ } /* if */ } /* if */ } /* if */ } /* if */ else printf (" MH_C_OR_NAME doesn't exist.
C Program Example local_rc = insert_root_attributes (*root_id); /* Create and insert the bilateral information */ if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Object BILATERAL INFORMATION \n"); local_rc = build_and_insert_bilateral_object (*root_id); /* Create and insert the content */ if (( local_rc == OM_RC_SUCCESS ) || (local_rc == ZGPI_RC_WARNING)) { if ( local_rc == ZGPI_RC_WARNING )
C Program Example printf (" Object OR NAME\n"); local_rc = build_and_insert_orname_object (*root_id); /* Create and insert the recipient descriptor */ if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); printf (" Object MESSAGE RD\n"); local_rc = build_and_insert_messagerd_object (*root_id); } /* if */ } /* if */ } /* if */ } /* if */ } /* if */ } /* if */ } /* if */ } /* if */ return (local_rc); } /* b
C Program Example max_descriptors) /* Number of elements in /* the descriptor list */ */ { unsigned short local_rc; /* Return code from the function call short len, exist; /* The return value from the stccpy function */ /* Position from the element in descriptor list*/ unsigned long string_offset, string_length, actual_number, total_number; /* /* /* /* unsigned short counter_2, counter ; /* Counter for the loop /* Counter for the loop String offset for GPI_OM_READ_ Length in octets of the string
C Program Example case case case case { printf (" %x", *octet_pointer ); octet_pointer++; } printf ("\n"); break; OM_S_TELETEX_STRING : OM_S_UTC_TIME_STRING : OM_S_IA5_STRING : OM_S_PRINTABLE_STRING : len = (short)stccpy (printout, descriptor_list[exist].value.z_string.elements, descriptor_list[exist].value.z_string.length + 1); printf (" %s %s \n",print_data[counter].text,printout); break; case OM_S_INTEGER : printf ( " %s %ld\n", print_data[counter].text, descriptor_list[exist].value.
C Program Example IM_T_TEXT, 0, &string_offset, string_length, data_string, &actual_number, &total_number ); /* /* /* /* /* /* /* /* /* /* /* Attribute type Value position Offset of the start of the string to read Number of string to be read Buffer to contain the strings The actual number of octets read by this call The total number of octets in this value */ */ */ */ */ */ */ */ */ */ */ if (( local_rc == OM_RC_SUCCESS ) || ( local_rc == ZGPI_RC_WARNING )) { if ( local_rc == ZGPI_RC_WARNING ) printf (
C Program Example /* the number of attributes in the message. */ /* f_desc_list contains the same attributes as */ /* print_data, but in the OM_descriptor structure. It */ /* is used as the input for GPI_OM_FETCH_, which */ /* will fill in the value fields. desc_list */ /* contains all the attributes from the same level as */ /* the object to be printed. */ /* The function will search through desc_list for */ /* the object identifier of local_type.
C Program Example local_rc = GPI_OM_FETCH_ ( desc_list[exist].value.object.
C Program Example total_string_len, /* Returns the total number of bytes total_string_len_2, /* Returns the total number of bytes max_PRINT_DEF = 7; /* Number of attributes to print char string_buffer[STRING_BUFFER_LEN], /* Buffer for the strings string_buffer_2[STRING_BUFFER_LEN]; /* Buffer for the strings PRINT_DEF print_arr[7] = { MH_T_ALTERNATE_RECIP_ALLOWED, MH_T_CONTENT_IDENTIFIER, MH_T_CONTENT_RETURN_REQUESTED, MH_T_CONTENT_TYPE, MH_T_CONVERSION_PROHIBITED, MH_T_DISCLOSURE_ALLOWED, MH_T_PRIORITY, };
C Program Example printf (" Bilateral Information\n"); print_object ( MH_T_BILATERAL_INFORMATION, max_PRINT_DEF, print_arr, f_descriptor_list, descriptor_list, actual_number); /* Print interpersonal message */ max_PRINT_DEF = 4; f_descriptor_list[0].type = IM_T_AUTO_FORWARDED; f_descriptor_list[1].type = IM_T_IMPORTANCE; f_descriptor_list[2].type = IM_T_SENSITIVITY; f_descriptor_list[3].type = IM_T_SUBJECT; print_arr[0].type = IM_T_AUTO_FORWARDED; print_arr[1].type = IM_T_IMPORTANCE; print_arr[2].
C Program Example printf (" IA5 Text Body Part\n"); print_object ( IM_T_BODY, max_PRINT_DEF, print_arr, f_descriptor_list, descriptor_list_2, actual_number_2); /* Print IPM identifier */ max_PRINT_DEF = 1; f_descriptor_list[0].type = IM_T_USER_RELATIVE_IDENTIFIER; print_arr[0].type = IM_T_USER_RELATIVE_IDENTIFIER; print_arr[0].text = " User Relative Id.
C Program Example print_object ( MH_T_MTS_IDENTIFIER, max_PRINT_DEF, print_arr, f_descriptor_list, descriptor_list, actual_number); /* Print eits */ max_PRINT_DEF = 1; f_descriptor_list[0].type = MH_T_BUILTIN_EITS; print_arr[0].type = MH_T_BUILTIN_EITS; print_arr[0].text = " Builtin Eits: "; printf (" Eits\n"); print_object ( MH_T_ORIGINAL_EITS, max_PRINT_DEF, print_arr, f_descriptor_list, descriptor_list, actual_number); /* Print or name */ max_PRINT_DEF = 6; f_descriptor_list[0].
C Program Example descriptor_list_3, &total_number, &actual_number, string_buffer, STRING_BUFFER_LEN, &actual_string_len, &total_string_len ); if (( local_rc == OM_RC_SUCCESS ) || (local_rc == ZGPI_RC_WARNING)) { if ( local_rc == ZGPI_RC_WARNING ) printf (" WARNING! number: %d \n", local_rc ); /* Print the two multivalued attributes */ for ( counter = 0 ; counter < 2 ; ++counter ) { local_rc = GPI_OM_EXAMINE_ ( descriptor_list_3[counter].value.object.
C Program Example print_arr[2].type print_arr[3].type print_arr[4].type print_arr[5].type = = = = MH_T_PRMD_NAME; MH_T_ORGANIZATION_NAME; MH_T_ORGANIZATIONAL_UNIT_NME_1; MH_T_SURNAME; print_arr[0].text print_arr[1].text print_arr[2].text print_arr[3].text print_arr[4].text print_arr[5].
C Program Example OM_descriptor f_descriptor_list[MAX_DESCRIPTORS], /* Descriptor list for fetch */ descriptor_list_out[MAX_DESCRIPTORS]; /* Descriptor list for output */ /* from fetch */ f_descriptor_list[0].
C Program Example unsigned long environment_object, /* /* /* /* /* /* outbound_object, available, inbound_object; char gateway_name[] = gateway_instance_name[] = mhs_mgr_name[] = gateway_password[] = local_identifier[32]; /* /* printf (" printf (" printf (" Object identifier of an object that represents the local environment Object identifier Indicates the availability of an unreserved message Object identifier */ */ */ */ */ */ "Gateway ", "Instance ", "$ZT1", "GATEWAY", Local identifier string that
C Program Example { printf (" BUILD_ROOT_OBJECT printf ("was successful! \n"); --> "); if ( rc == ZGPI_RC_WARNING ) { printf ("\n *********** WARNING! **********\n"); show_gpi_status (ZGPI_ANY); } /* Transfer out the root object */ printf (" Call GPI_MT_TRANSFER_OUT_"); rc = GPI_MT_TRANSFER_OUT_ ( session, outbound_object, local_identifier, &local_identifier_len, OM_FALSE /* retain */ ); if (( rc == OM_RC_SUCCESS ) || ( rc == ZGPI_RC_WARNING )) { printf (" --> was successful! \n"); if ( rc == ZGPI_RC_
C Program Example show_gpi_status (ZGPI_ANY); } /* Show the root object */ printf (" Call SHOW_MESSAGE \n"); rc = print_root_object inbound_object ); if (( rc == OM_RC_SUCCESS ) || ( rc == ZGPI_RC_WARNING )) { printf ("\n SHOW_"); printf ("MESSAGE "); printf ("--> was successful! \n"); if ( rc == ZGPI_RC_WARNING ) { printf ("\n *********** WARNING! "); printf ("**********\n"); show_gpi_status (ZGPI_ANY); } /* End transfer in */ printf (" Call GPI_MT_FINISH_TRANSFER_IN_"); rc = GPI_MT_FINISH_TRANSFER_
C Program Example else { printf ("\n *** No message available ! ****\n"); } /* else */ } /* if */ else { printf ("\n GPI_MT_WAIT failed! Error: %d \n", rc ); show_gpi_status (ZGPI_ANY); } /* else */ } /* if */ else { printf ("\n GPI_MT_TRANSFER_OUT failed! "); printf ("Error: %d \n", rc ); show_gpi_status (ZGPI_ANY); } /* else */ } /* if */ else { printf ("\n BUILD_ROOT_OBJECT failed! "); printf ("Error: %d \n", rc ); show_gpi_status (ZGPI_ANY); } /* if */ /* Close the session */ printf (" Call GPI_CLOSE_
C Program Example } } /* else */ /* main */ Note. The following is a sample of output from the C program example.
C Program Example Call Call Call Call Remove the attribute MH_T_RECIPIENT_NUMBER Insert the attribute MH_T_RECIPIENT_NUMBER with new value Insert the object into the root object BUILD_ROOT_OBJECT --> was successful! GPI_MT_TRANSFER_OUT_ --> was successful! GPI_MT_WAIT_ GPI_MT_WAIT_ is waiting for a message GPI_MT_WAIT_ --> was successful! GPI_MT_START_TRANSFER_IN_ --> was successful! SHOW_MESSAGE The received object is a message.
C Program Example Organization Name: MTA1 Organization Unit Name: GWUSERS Surname: UAGW11 Recipient Descriptors Explicit Conversion: -1 MTA Report Request: 1 MTA Responsibility: 1 Originator Report Request 2 Recipient Number: 2 OR Name Admd Name: POSTMASTER1 Country Name: US Prmd Name: DEVELOPMENT Organization Name: MTA1 Organization Unit Name: GWUSERS Surname: UAGW12 SHOW_MESSAGE Call GPI_MT_FINISH_TRANSFER_IN_ Call GPI_CLOSE_ --> --> --> was successful! was successful! was successful! ****************
C Review of X.400 and OSI/MHS This appendix is a brief summary of key X.400 and OSI/MHS concepts. It provides a quick orientation to the X.400 gateway environment for readers who are new to networking. The topics covered are: • • • • X.400 X.400 messages Compaq OSI/MHS X.400 gateways X.400 X.400 is the official messaging protocol for the European community and for Government OSI Profile (GOSIP) networks in the United States. X.400 defines a functional model for a message handling system (MHS).
Review of X.400 and OSI/MHS X.400 Messages X.400 Messages There are three types of X.400 messages: • • • User messages (or simply messages) Probes Reports As shown in Table C-1, the three types differ in structure and purpose. Table C-1. X.400 Message Types Type Purpose Structure Message Conveys user information Envelope and content Probe Verifies deliverability Envelope only Report Conveys status information Envelope and content A message is sent between users.
Review of X.400 and OSI/MHS Compaq OSI/MHS X.400 has detailed rules about envelopes and IPM content. The rules that relate to the Compaq GPI are specified in two protocols: • • P1, for envelopes P2, for IPM content Because envelopes are normally seen only by MTAs, P1 is sometimes called the MTA-to-MTA protocol. Because P2 relates to IPM content, P2 is sometimes called the IPM protocol. Compaq OSI/MHS OSI/MHS is the Compaq implementation of an X.400 MTA. It is a store-and-forward X.
Review of X.400 and OSI/MHS X.400 Gateways Figure C-4. X.400 Gateway Message Handling System Message Transfer System NonStop System Proprietary Messaging System Gateway MTA OSI/ MHS OSI/ MHS User User CDT 904.CDD X.400 access allows proprietary systems to exchange messages with the global MHS (Figure C-4). They can also exchange messages with other proprietary systems that access the MHS. An X.
D EDI Concepts This appendix summarizes key electronic data interchange (EDI) concepts. It provides a conceptual framework for reference information in the GPI Reference Manual. The topics covered are: • • • • EDI and EDI messaging The EDI message structure EDI notifications, forwarding, and responsibility EDI extensions What Is Electronic Data Interchange (EDI)? EDI is the electronic exchange of business data, such as invoices and purchase orders.
EDI Concepts EDI Message (EDIM) Structure Figure D-1. The EDI Messaging System EDI Messaging System EDI UA EDI AU MTS MTA MTA OSI/MHS GPI Trading Partner EDI UA Trading Partner EDI MS CDT 905.CDD In addition to the MTS, the EDIMS also consists of numerous peripheral objects of three kinds: EDI user agents (EDI-UAs), EDI access units (EDI-AUs), and EDI message stores (EDI-MSs).
EDI Concepts EDIMs and X.400 The EDIM body is further divided into one primary body part, and optionally, one or more additional body parts. The primary body part contains the content of a single EDI interchange (which may be original or forwarded). Additional body parts contain information related to the EDI interchange, such as drawings or explanatory text. The GPI supports X.435 explicitly. It provides attributes and object classes that conform closely to X.435 protocols.
EDI Concepts EDI Notifications and therefore cannot encode EDI interchanges in the form of EDIMs. These components might, for instance, encode the interchange as undefined content of an X.400 message (“the P0 method”). Alternately, they might encode the interchange as the body part of an interpersonal message (IPM), extracting information from the interchange to put into the IPM header (“the P2 method”). Because the GPI supports CCITT Recommendation X.
EDI Concepts EDIM Forwarding Each type of notification relates to acceptance or refusal of responsibility for the EDIM by the recipient: • • • A forwarded notification reports that responsibility for an EDIM has been forwarded along with the subject EDIM. A forwarded notification is generated by a receiving EDI-UA, EDI-MS, or physical access delivery unit (PDAU), when EDIM responsibility cannot be given to the associated user, and the EDIM is forwarded to another recipient.
EDI Concepts EDI Extensions Figure D-4. Forwarding an EDIM Forwarded EDIM EDIM (EDI-C-EDIM) Heading Forwarding EDIM EDIM (EDI-C-EDIM) Heading EDI-C-EDI-HEADING Primary Body Part Primary Body Part EDI-C-EDIM-BODYPART Add'l Body Part n Add'l Body Part n Add'l Body Part n+1 Add'l Body Part n+1 EDI-C-EDIM-EX-DF-BODYPART EDI-C-EDIM-EX-DF-BODYPART CDT 908.
Glossary The following glossary defines terms used in this manual and in other Compaq OSI/MHS manuals. Both industry-standard terms and Compaq terms are included. This list covers Compaq OSI/MHS as a whole; therefore, not all terms given here are used in this particular manual. abstract syntax. A representation of the way in which components of information are to be specified in a communication.
Glossary ASE (application service element) ASE (application service element). A set of functions in the Application Layer that supports either a large range of applications or a particular type of application, such as file transfer or transaction processing. ASN.1 (Abstract Syntax Notation One). A data description language for expressing abstract syntaxes in OSI. See also abstract syntax and BER. association. In OSI, a connection between Application Layer entities. See also connection.
Glossary BER (Basic Encoding Rules) BER (Basic Encoding Rules). The standard for an associated transfer syntax (CCITT Recommendation X.209). These rules were defined to provide a transfer syntax for use by ASN.1 compilers. bind. The act of establishing a connection. An MTA bind enables one MTA to establish an association with another MTA; an MS bind enables a user agent to establish an association with a message store. bit string. A series of bits treated as a unit. body part.
Glossary command file command file. An EDIT file that contains sequences of commands. Sometimes called an OBEY file. command message. An SPI message, containing a command, sent from an application program to a subsystem. See also response message or event message. command/response interface. In DSM, a management interface that performs operations on subsystem-defined objects. common definition.
Glossary content content. One of two basic parts of a message or report, containing the information to be conveyed to the recipients. The other part is called the “envelope.” Probes contain a description of the content rather than the content itself. context token. In DSM programmatic interfaces, a token in an SPI response message that indicates (by its presence or absence) whether or not the response is continued in the following message. control and inquiry.
Glossary CUG object CUG object. An object type, used in OSI/MHS management interfaces, that identifies a closed user group to the Compaq OSI/MHS subsystem. CUGMEMBER object. An object type, used in OSI/MHS management interfaces, that identifies an individual member of a closed user group. data communications standard definitions. In DSM, the set of declarations provided by Compaq for use in all management applications that manage or retrieve event messages from Compaq data communications subsystems.
Glossary diagnostic code diagnostic code. A value indicating why a message was not delivered (called a non-deliverydiagnostic code in the X.411 standard). Distributed Systems Management. See DSM. distribution list. A list of users to whom it is possible to address messages collectively. The distribution list name logically represents the names of all members of the list. OSI/MHS and Transfer both support distribution lists. distributor.
Glossary EDI messaging (EDIMG) EDIM is transferred as X.400 message content accompanied by an envelope (which conforms to P1 protocol). The format of the message content is similar to, but not the same as, a P2 message. In addition to the MTS, the EDIMS also consists of numerous peripheral objects of three kinds: EDI user agents (EDI-UAs), EDI message stores (EDI-MSs), and EDI access units (EDI-AUs). These peripheral objects can be viewed as access points for EDI users. EDI messaging (EDIMG).
Glossary Electronic data interchange (EDI) Electronic data interchange (EDI). The automated exchange of structured business data, such as invoices and purchase orders. element. See string element. element of service. In OSI, a feature or function defined as part of a service. empty response record. In DSM programmatic interfaces, a response record containing only a return token with a value that means “no more response records.” EMS (Event Management Service).
Glossary error token error token. In DSM programmatic interfaces, a token in a response message that indicates the reason an error occurred in performing a programmatic command. Compaq subsystems enclose each error token in an error list, which can also contain additional information about the error. A response record must contain a return token and can also contain error lists to explain the error further. event. In DSM, a significant change in some condition in the system or network.
Glossary external tracing extensions contain one or more instances of the MH-C-EXTENSIONS class. See also BER. external tracing. The recording of actions taken by a management domain with respect to a message, probe, or report. See also internal tracing. extensible structured token. In DSM programmatic interfaces, a token consisting of a token code and a value that is an extensible structure. Extensible structures can be extended by adding new fields at the end.
Glossary GATEWAY object GATEWAY object. An object type, used in OSI/MHS management interfaces, that defines and controls the Transfer X400 gateway or a gateway application based on the Gateway Programmatic Interface (GPI). GI (gateway interface) class. The OSI/MHS CLASS object that identifies the set of all GI groups in an OSI/MHS subsystem. GIP (Gateway Interface Process). The server that moves messages between a proprietary message system and OSI/MHS.
Glossary Install program Install program. The Compaq program that installs new or updated software on the system from SUT tapes and creates the ISVs. installation file. The file created through the OSI/MHS installation procedure that contains the volume and subvolume locations for objects, the security classifications, and the installation steps. installation procedure. The OSI/MHS procedure that creates a default edit file and prompts you to modify that file to fit your configuration requirements.
Glossary LAN all of the OSI/MHS object files (MTA, RTS, SC, MS, RS, GI, LO, and MHSMGR), softdocs, and installation macros. LAN. A local area network. See also TLAM. layer. A grouping of related functions in the OSI Reference Model. See Application Layer, Data Link Layer, Network Layer, Physical Layer, Presentation Layer, Session Layer, or Transport Layer. link. A physical and logical path between two adjacent computers or other devices.
Glossary LUA (local user agent) LUA (local user agent). A process that submits and retrieves messages on behalf of a user, through a message store on the same system as the user agent. mailbox. A location in an MS SQL database that stores messages for one user. Each MS group can have up to 1000 mailboxes to support up to 1000 users. management application. In DSM, an application process that opens a management or subsystem process to control a subsystem.
Glossary MIB (management information base) MIB (management information base). A database used by the OSI manager process to store and retrieve configuration information and information about applications. mnemonic O/R address. An O/R address that identifies a user by terms that are easily remembered. See also numeric O/R address. MON object. An object type, used in OSI/MHS management interfaces, that enables you to address commands to the OSI/MHS manager process.
Glossary MTA object MTA object. An object type, used in OSI/MHS management interfaces, that defines adjacent MTAs and their attributes to the OSI/MHS subsystem. MTA process. See MRP process. MTS (Message Transfer System). The part of a message handling system that contains the MTAs and that permits communication between user agents. MTS identifier. A unique identifier that distinguishes a communication from all other communications ever conveyed by the MTS within the MHS. multithreaded process.
Glossary nondelivery report nondelivery report. A report generated by the MRP when it cannot deliver a message to the recipients, or when it cannot deliver a report to the originator of the message or probe. nonreceipt notification. An indication to the sender of a communication that the communication was not received by the intended recipients. nonsensitive command.
Glossary object identifier object identifier. In ASN.1, a set of values identifying an object in an ASN.1 abstract syntax notation defined by the CCITT. In the GPI, a unique identifier of a particular object generated by the GPI service when the client program creates a new object, copies an object, or reserves an object. The client program passes the object identifier to any GPI procedure operating on the object. A GPI object identifier is not related to an ASN.1 object identifier. object management.
Glossary OSI/MHS (Open Systems Interconnection/Message Handling System) configuration information about the OSI environment. There is one OSI manager process per OSI/AS subsystem. OSI/MHS (Open Systems Interconnection/Message Handling System). The Compaq implementation of an X.400 message handling system for Compaq NonStop systems. OSI/MHS database. The database that consists of the registration database and OSI/MHS configuration database. OSI/MHS ISV. The installation subvolume for the OSI/MHS release.
Glossary P2 protocol P2 protocol. The X.400 interpersonal message (IPM) user agent protocol, which defines the format by which one user agent (UA) sends an interpersonal message (IPM) to one or more other UAs. P2 message. An X.400 message that consists of a heading followed by a series of data blocks, called body parts. The heading contains the message originator, recipients, and other service information. Each body part can contain a different form of data, and messages can be nested within body parts.
Glossary PDU store PDU store. The database that stores messages in an X.400 system. A PDU store consists of a data file and a log file. Each MR, MS, RS, and LO group has its own PDU store. Physical Layer. Layer 1 in the OSI Reference Model. This layer establishes the actual physical connection between the network and the computer equipment. Protocols at the Physical Layer include rules for the transmission of bits across the physical medium and rules for connectors and wiring. Port Access Method (PAM).
Glossary process process. A running entity that is managed by the operating system, as opposed to a program, which is a collection of code and data. A process is a unique execution of a program. PROCESS object. An object type, used in OSI/MHS management interfaces, that defines a process to the OSI/MHS subsystem. You use the PROCESS object to trace and monitor OSI/MHS processes. programmatic command. In DSM, a command issued by a program rather than by a human operator. See also interactive command.
Glossary recipient recipient. A person or application that receives a message from a message handling system. registration database. An OSI/MHS database that consists of three files: APPL, route, and adjacent MTA. reliable transfer service. See RTSE. remote MTA. An adjacent or nonadjacent MTA. Any MTA other than your local OSI/MHS subsystem. Remote Operations Service. See ROSE. remote system. In Compaq terms, any system within an Expand network that is not the local system. remote user agent. See RUA.
Glossary return token return token. In DSM programmatic interfaces, the token that indicates whether a command was successful and, if not, why it failed. The token code for the return token is ZSPI-TKN-RETCODE. Its value consists of a single integer field. See also error token. root object. In the GPI, a message, probe, report, or P1-encoded object. ROSE (Remote Operations Service Element).
Glossary RTSE (reliable transfer service element) RTSE (reliable transfer service element). An Application Layer service definition and protocol supporting the reliable exchange of application data, defining such services as recovery from end-to-end failures and reporting delivery status to the sender. In OSI/MHS, the RTS process implements the RTSE. RTS (reliable transfer service) process. A process in the MR group that implements the RTSE protocol and accesses the PDU store to read and write messages.
Glossary sensitive command sensitive command. In DSM, a command that can be issued only by a restricted set of Guardian 90 users, such as the owner of a subsystem process. For Compaq data communications subsystems, the sensitive commands are those that can change the state or configuration of objects, start or stop tracing, or change the values of statistics counters. See also nonsensitive command. service. A set of primitives (operations) that an OSI layer provides to the layer above it.
Glossary single-valued attribute single-valued attribute. An attribute that has only one value. Site Update Tape. See SUT. SNPA (subnetwork point of attachment). A real, physical address, identifying the point of attachment to a subnetwork. softdoc. A text file in edit-file (code 101) format that is part of a software product version or an interim product modification (IPM) in the same subvolume.
Glossary SSID (subsystem ID) SSID (subsystem ID). In DSM programmatic interfaces, a data structure that uniquely identifies a subsystem to SPI. It consists of the name of the owner of the subsystem (such as Compaq), a subsystem number that identifies that particular subsystem, and a subsystem version number. The subsystem ID is an argument to most of the SPI procedures. string element. The bits of a bit string or the octets of an octet string. string segment.
Glossary superobject data communications subsystems refer to summary states rather than to states. Examples of summary states are STARTED, STOPPED, SUSPENDED, and ABORTING. superobject. An object that has other objects for one or more of its attributes. SUT (site update tape). The tape on which Compaq ships its software for installation. The product files on the SUT tape are grouped into distribution subvolumes (DSVs), the names of which appear on the last part of the packing list.
Glossary token code for the subsystem. In event messages, a token normally represents an item of information about an event or about the event message itself. See also header token. token code. In DSM programmatic interfaces, a 32-bit value that identifies a token. A token code consists of a token type (16 bits) and a token number (16 bits). See also token number, token type, and token map. token map.
Glossary TSEL (transport selector) TSEL (transport selector). An address between the Transport and Session Layers, through which connections are established and maintained. A single TSEL can service one or more connections simultaneously and can refer to one or more TSAPs. TSP process. The OSI transport services process. type. See attribute type. UA (user agent). The functional component that represents the user in an X.400 message handling system.
Glossary working subvolume working subvolume. A subvolume that contains temporary files used by the OSI/MHS subsystem processes. There is a separate working subvolume for each process group. X.25 access method. See X25AM. X.25 network. Any network or subnetwork linked using X.25 standards. X.25 standards are CCITT standards that define packet-switching carrier communication in the Network Layer over wide area networks (WANs). X25AM (X.25 access method).
Glossary $RECEIVE OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 Glossary -34
Index A Abbreviations xix Acronyms xix actual-info-length parameter 6-4, 6-9 actual-number parameter of GPI_OM_EXAMINE_ 5-37 of GPI_OM_LIST_ 5-42 of GPI_OM_READ_ 5-46 actual-string-length parameter of GPI_OM_EXAMINE_ 5-38 of GPI_OM_FETCH_ 5-33 of GPI_OM_LIST_ 5-42 ADMD name 5-12 all parameter 5-49 API 1-2 APIA-1984 specification xii APPL object 1-4 approx-total-number parameter 5-46 Archive queue 2-10 Archived object 2-10 Archiving root objects 5-49 Arrival time 5-31 Attribute 3-11 counting attributes in an
Index D Creating a subobject 5-18 Creating an object 2-6, 5-17 Creating an object with defaults 3-10, 5-18 Criticality, X.400 4-6 Criticality, X.
Index F Error codes 6-1 error-class parameter 6-3 error-qualifier parameter 6-3 error-source parameter 6-4 Extensions, X.400 4-5 Extensions, X.
Index H GPI library (continued) primitives 1-5 procedure declaration files 2-12 sequence of procedures 5-2 GPI operation 1-1 GPI service 1-1, 1-5 GPIDEFS file 2-11 GPIDEFSH file 2-11 GPIEXT file 2-12 GPIEXTH file 2-12 GPI_CLOSE_ procedure 2-3, 5-13 GPI_INITIALIZE_ procedure 2-2, 5-5 and fault recovery 6-22 example of 5-9 parameters for 5-5 GPI_MT_FINISH_TRANSFER_IN_ remove parameter to 5-47 GPI_MT_FINISH_TRANSFER_IN_ procedure 2-8, 5-47 example of 5-49 parameters for 5-48 GPI_MT_START_TRANSFER_IN_ procedu
Index I I Identifier object 2-4, 3-8, 5-18 session 1-5, 5-12 in inbound processing 2-10 Inbound processing 1-8, 5-28 and fault recovery 4-4 diagram of 1-8 editing a root object 5-50 finishing inbound transfer 2-8, 5-47 retrieving information from a root object 5-31 starting inbound transfer 2-8, 5-30 waiting for a root object 2-8, 5-28 Information buffer 6-9 buffer structures 6-10 description of formats 6-16 parameters for 6-9 reading of 6-11 info-buffer parameter 6-4, 6-9 info-buffer-length parameter 6-4
Index N Message handling system See MHS Message originator C-1 Message recipient C-1 Message relay process See MRP Message Transfer Agent 1-1 Message transfer agent See MTA Message transfer procedures 2-7 Message transfer system See MTS MHS manager name 1-4, 4-2, 5-11 MHS manager process 1-5 and fault recovery 6-22 and GIPs 1-5 and GPI configuration 4-1 MHS-mgr-name parameter 5-11 MHS-mgr-name-length parameter 5-11 MH-C-EXTENSION object class 4-8 MRP 1-5 and fault recovery 6-22 MTA 1-1 MTS and EDI messagi
Index P object parameter (continued) of GPI_OM_REMOVE_ 5-51 Object states 2-10 Object tree 3-10 table size 5-6 old-status parameter 6-3 OM-T-CLASS attribute 3-5, 3-8, 3-14 Opening a GPI session 2-3 original parameter 5-54 OSI/MHS 1-1 Outbound processing 1-7, 5-14 and fault recovery 4-3 building a root object 5-15 diagram of 1-7 outbound transfer 5-25 Output queue 1-5, 1-7, 5-25 P P1 User Exit 1-9 P1-EXIT 1-9, 2-10, 5-47 P1-EXIT gateway 1-1, 4-2 P1-EXIT message flow 1-9 P1-EXIT operation 1-6, 1-9 P1-EXIT
Index S Recommendations X400-X420 xii Recovering from errors 6-1 recovering from a client failure 6-22 recovering from a GIP failure 6-22 recovering from GPI errors 6-22 Reinitializing GPI sessions 6-22 remove parameter 2-10, 5-49 toGPI_MT_FINISH_TRANSFER_IN_ 2-10 Removing an attribute value 2-6, 5-50, 5-51 Removing an object 5-51 request-type parameter 6-3 Reserved object 2-10 Reserving an object 5-31 Responsibility for inbound information 4-4 Responsibility for outbound information 4-3 Responsibility, E
Index T string-buffer parameter of GPI_OM_EXAMINE_ 5-37 of GPI_OM_FETCH_ 5-33 of GPI_OM_LIST_ 5-42 string-buffer-length parameter of GPI_OM_EXAMINE_ 5-38 of GPI_OM_FETCH_ 5-33 of GPI_OM_LIST_ 5-42 string-offset parameter of GPI_OM_READ_ 5-45 of GPI_OM_WRITE_ 5-23 Subobject 3-3 creating 5-18 Success code 6-1 Superobject 3-3 Supported extensions 4-6 swap-volume parameter 5-5 syntax parameter 5-23 U T Wait manager process 1-6 and fault recovery 6-22 Waiting for an inbound root object 5-28 Warning code 6-1
Index Z Z ZGPI-STDANGLING-OBJ structure 6-18 ERROR-ATTR structure 6-17 INFO-3 structure 6-19 INFO-4 structure 6-20 INFO-5 structure 6-21 ZOSIGI subvolume 2-12 Z-STRUCT-TYPE 6-16 OSI/MHS Gateway Programmatic Interface (GPI) Programming Guide—424822-001 Index -10
