OSI/MHS P7 Application Programmatic Interface (P7 API) Manual Abstract This manual describes the P7 Application Progammatic Interface (P7 API) to the Compaq OSI/MHS subsystem. It contains programming and reference information for C programmers who use the P7 API procedures. It also includes configuration, management, and troubleshooting information.
Document History Part Number Product Version Published 068018 OSI/MHS P7 API C31 June 1992 094863 OSI/MHS P7 API C32 March 1993 099934 OSI/MHS P7 API D20 September 1993 424825-001 OSI/MHS P7 API D42 December 1999 Ordering Information For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact your local sales representative. Document Disclaimer Information contained in a manual is subject to change without notice.
OSI/MHS P7 Application Programmatic Interface (P7 API) Manual Glossary Index Figures Tables What’s New in This Manual v Manual Information v New and Changed Information v About This Manual vii Who Should Read This Manual? vii What’s in This Manual? vii What Related Publications Are Available? viii xi Your Comments Invited Notation Conventions xii Abbreviations xvi 1.
2. Planning and Writing Your Application (continued) Contents 2. Planning and Writing Your Application (continued) Writing a P7 API Client Application 2-3 Developing a Program Structure 2-3 Managing the P7 API Environment 2-5 Transferring Data 2-7 Creating an Executable Program 2-11 3.
Figures Contents Figures Figure i. Related Publications ix Figure ii. Compaq OSI/MHS Library Map Figure 1-1. A Client Application 1-1 Figure 1-2. Connecting to OSI/MHS Figure 1-3. An LO Group Figure 1-4. Local and Remote UAs in an OSI/MHS Subsystem Figure 2-1. P7API Program Flow Figure 2-2. Opening a Session Figure 2-3. Binding to an MS Group 2-9 Figure 3-1. Sample P7 API Procedure Call Description 3-4 xi 1-3 1-4 1-7 2-5 2-7 Tables Table 2-1.
Contents OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 iv
What’s New in This Manual Manual Information Abstract This manual describes the P7 Application Progammatic Interface (P7 API) to the Compaq OSI/MHS subsystem. It contains programming and reference information for C programmers who use the P7 API procedures. It also includes configuration, management, and troubleshooting information. Product Version OSI/MHS P7 API D42 Supported Releases This manual supports G06 and D41 releases and all subsequent releases until otherwise indicated in a new editon.
What’s New in This Manual New and Changed Information OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 vi
About This Manual This manual describes the Compaq P7 Application Programmatic Interface (P7þAPI). The P7þAPI provides a programmatic interface between a user agent (or client application) and the Compaq Open Systems Interconnection/Message Handling System (OSI/MHS) on the same system. The P7þAPI eliminates the need for client applications to use the underlying OSI layers to reach the local OSI/MHS subsystem.
About This Manual • What Related Publications Are Available? Appendix E, “C Language Example Program,” is a sample C language program that shows how to call each P7þAPI procedure. What Related Publications Are Available? The related publications fall into three categories: documents prepared by standards groups, Compaq programming manuals, and other Compaq OSI/MHS manuals. The following subsections list and describe these publications.
Compaq Programming Manuals About This Manual • • C Reference Manual Transaction Application Language (TAL) Reference Manual Figure 1 shows the related publications that you may wish to consult while developing a P7 API program. Figure i. Related Publications Guardian Programmer's Guide CCITT Blue Book, Recommendations X.220X.290 Guardian Procedure Calls Reference Manual TAL Reference Manual For information on the Compaq environment For information on MHS + ASN.
About This Manual Other Compaq OSI/MHS Manuals Other Compaq OSI/MHS Manuals The following manuals provide additional information about Compaq OSI/MHS: • • • • • • OSI/MHS 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. Compaq OSI/MHS Library Map OSI/MHS Orientation Guide Concepts OSI/MHS GPI Programming Guide OSI/MHS GPI Reference Manual OSI/MHS Configuration and Management Manual OSI/MHS Administrative Utility (AU) Manual OSI/MHS P7 API Manual Programming Management Methods and Tools Management Reference for Operators Operator Messages Manual Reference for Automating Management OSI/MHS Management Programming Manual OSI/MHS SCF Reference Manual CDT 999.
About This Manual Notation Conventions 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. Be sure to include your name, company name, address, and phone number in your message. If your comments are specific to a particular manual, also include the part number and title of the manual.
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 Notation for Management Programming Interfaces [ ] 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.
Abbreviations About This Manual !r. The !r notation following a token or field name indicates that the token or field is required. For example: ZCOM-TKN-OBJNAME !o. token-type ZSPI-TYP-STRING. !r The !o notation following a token or field name indicates that the token or field is optional. For example: ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. !o Abbreviations The following list defines abbreviations used in this manual and in other Compaq OSI/MHS manuals.
About This Manual G3. Group 3 (facsimile) G4. Group 4 (facsimile) GIP. Gateway Interface Process (Compaq term) GPI. Gateway Programmatic Interface (Compaq term) IA5. International Alphabet No. 5 IDU. Internal data unit IM. Interpersonal messaging IPC. Interprocess communication IPM. Interpersonal message IPN. Interpersonal notification ISO. International Organization for Standards MD. Management domain MH. Message handling MHS. Message handling system MOTIS. Message-Oriented Text Interchange System MPDU.
About This Manual Abbreviations OSI/MHS. Open Systems Interconnection/Message Handling System (Compaq term) P1. Protocol 1 (message-transfer protocol) P2. Protocol 2 (interpersonal-messaging protocol) P3. Protocol 3 (message-submission-and-delivery protocol) PDAU. Physical delivery access unit PDU. Protocol data unit PRMD. Private management domain RTS. Reliable transfer service RTSE. Reliable Transfer Service Entity SC. Store cleaner SCF. Subsystem Control Facility (Compaq term) SCP.
1 Introduction to the P7 API The Compaq P7 Application Programmatic Interface (P7 API) provides local access to the message store (MS) of the Compaq Open Systems Interconnection/Message Handling System (OSI/MHS). You use the P7 API to develop a local user agent (LUA) that provides the interface between the user and the message store of the local OSI/MHS subsystem.
Introduction to the P7 API The P7 API The P7 API The P7 API product is Compaq’s implementation of an API that provides the services of a P7 message store access protocol. The P7 protocol is the means by which an X.400 user agent submits messages to and retrieves messages from the message store of an X.400 message handling system (MHS). Although the Compaq P7 API is not based on any X.400 API standards, it is modeled after X.229: Remote operations: protocol specification, in Recommendations X.220X.
OSI/MHS Components Used by the P7 API Introduction to the P7 API Figure 1-2. Connecting to OSI/MHS OSI/MHS Subsystem MHSMGR MS Group Client Application P7 API LO Group User MR Group CDT 102.CDD The following subsections describe the MHS manager and the LO, MR, and MS groups. “Submission Operations,” under Transferring data in Section 2 describes the path of P7 SUBMIT operations in more detail.
OSI/MHS Components Used by the P7 API Introduction to the P7 API Figure 1-3. An LO Group OSI/MHS Subsystem LO Group LO MS Groups MR Groups LO PDU Store CDT 103.CDD LO processes and LO PDU stores are described in the following subsections. Local Operations (LO) Process.
Introduction to the P7 API P7 API Client Applications Message Store (MS) Group The message store (MS) group is used for long-term storage of messages. With a message store, the client application does not have to be connected to the subsystem when the message is delivered to the message store. You can connect to the OSI/MHS subsystem from the P7 API client application whenever you want to read or send messages.
Introduction to the P7 API P7 Operations P7 Operations The P7 operations that can be performed using a P7 API client application are: • • • Administration • • MSBIND MSUNBIND Submission • • • MESSAGE SUBMISSION PROBE SUBMISSION CANCEL DEFERRED Retrieval • • • • • SUMMARIZE LIST FETCH DELETE REGISTER-MS (change-credentials and list- and fetch-attribute-defaults only) The contents of the P7 operations are as follows: • • MSBIND and MSUNBIND operations require data to be structured like the use
Local User Agents Introduction to the P7 API Figure 1-4. Local and Remote UAs in an OSI/MHS Subsystem User User Local UA Local UA OSI/MHS Subsystem LO Group MR Group SC LO MRP RTS MS Group RS Group MS RS OSI/AS OSI/TS X25AM TLAM X.400 Network OSI/MHS Other MTA OSI/MHS Other MTA Remote UA Other MTA User Remote UA Remote UA User User CDT 104.CDD For more information on remote UAs, see the OSI/MHS Configuration and Management Manual.
Introduction to the P7 API Local User Agents OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 1 -8
2 Planning and Writing Your Application This section describes each step you take when planning and writing a P7 API client application. The first part of the section covers planning considerations; the second part covers writing considerations. Planning a P7 API Client Application To • • • • • plan your P7 API client application, you need to: Verify P7 API requirements. Determine the services required from OSI/MHS and the P7 operations needed to acquire those services.
Planning and Writing Your Application Determining the Services Required Determining the Services Required In planning a client application, you need to consider what you want the application to do. From those considerations, you then determine what services you require from the OSI/MHS subsystem. For example, if you plan to retrieve messages from an OSI/MHS mailbox, you might need your application to: 1. Bind to the OSI/MHS subsystem. 2.
Planning and Writing Your Application Planning for Security Planning for Security The initiator credentials (or user’s password for the MS APPL object) passed as part of an MSBIND operation must match those expected by the local OSI/MHS subsystem. If the credentials are correct, the MSBIND operation is completed and the client application can issue P7 operations.
Planning and Writing Your Application Developing a Program Structure Table 2-1. Sequence of P7 API Procedure Calls Step Action to Take Procedure(s) to Call 1 Initialize P7 API memory space. LOS_INITIALIZE_ 2 Open a P7 API session. LOS_OPEN_ 3 Bind to an MS group by using the following three steps: 4 5 6 7 1. Send an MSBIND argument, then wait for completion on the send file. LOS_DT_SEND_ , AWAITIOX 2. Check for completion on the send file, then wait for completion on the result file.
Managing the P7 API Environment Planning and Writing Your Application received, you then call the LOS_DT_FINISH_SEND_ procedure if completion occurred on a send file, or LOS_DT_FINISH_RESULT_ if completion occurred on a result file. For a description of the AWAITIOX procedure, see the Guardian Procedure Calls Reference Manual. Figure 2-1 shows the task sequence in the form of a flow diagram. Figure 2-1.
Planning and Writing Your Application Managing the P7 API Environment Initializing the Environment The first P7 API procedure that you call from the client application must be LOS_INITIALIZE_ . This procedure initializes the P7 API environment by setting up an internal workspace that enables the other P7 API procedures to operate correctly. LOS_INITIALIZE_ has no parameters. The workspace is an area of extended memory dedicated to the P7 API procedures.
Transferring Data Planning and Writing Your Application Figure 2-2. Opening a Session OSI/MHS Subsystem Client Application 1 5 2 P7 API MHSMGR 4 6+7 3 LO Group CDT 202.CDD Closing a Session You call the LOS_CLOSE_ procedure to close a P7 API session. LOS_CLOSE_ takes the send file number and result file number as input parameters. After this procedure, these file numbers become invalid, even if an error occurs while the procedure is executing. You should close a session: 1.
Planning and Writing Your Application • Transferring Data Unbinding from an MS group Note. Because the administration operations, MSBIND and MSUNBIND, bracket all other P7 operations, they are presented in their own subsections below. Additionally, you should note that the following subsections do not describe the SUBMISSION CONTROL operation. For more information on this operation, see Section 3 and X.419 MHS: Protocol Specifications in Recommendations X.400-X.420 (1988).
Transferring Data Planning and Writing Your Application Figure 2-3. Binding to an MS Group OSI/MHS Subsystem 1 Client Application 3 2 P7 API MS Group LO Group 5 4 MS Group CDT 203.CDD Sending P7 Submission and Retrieval Arguments After you have established an application association, you can send a P7 submission or retrieval request to the OSI/MHS subsystem. To send data, you use the LOS_DT_SEND_ procedure call to send the P7 argument. The P7 argument is an encoded ROSE encapsulated P7 operation.
Planning and Writing Your Application Transferring Data For each active client application, the P7 API can keep track of up to 10 message submissions for which a response has not yet been received. The P7 API does this tracking by means of a unique invoke identifier (ID) that is assigned to each message submission. The P7 API guarantees that a message is sent only once by not resubmitting the same invoke ID more than once.
Planning and Writing Your Application Creating an Executable Program Retrieval Operations Retrieval Operations. The P7 API supports the following retrieval operations: • • • • • LIST FETCH SUMMARIZE DELETE REGISTER-MS When a client application issues a LIST, FETCH, SUMMARIZE, DELETE, or REGISTER-MS request, the LO group passes the request to the MS group. The MS group then processes the request and creates the response. The response PDU is formed in memory and is not stored in the MS PDU store.
Planning and Writing Your Application Creating an Executable Program The filename for the P7 API object file is P7PILIB. The names for the C and TAL declarations files are P7PIEXTH and P7PIEXT, respectively. To include the declaration files in the client application, use the C preprocessor directive #include for C language programs or the ?SOURCE directive for TAL language programs. These directives copy the contents of the declaration file into the client application.
3 Procedure Calls This section contains detailed reference information about the P7 API procedures provided with the OSI/MHS subsystem. The information includes: • • • A description of the object and declaration files provided by Compaq. A description of the procedure names and the two categories of procedures.
Procedure Names and Categories Procedure Calls disk is the name of the volume where the software is located. By default, the Install program places these files on $SYSTEM. The actual location of these files can be $SYSTEM or another volume chosen by your site. For applications coded in C, you must use the #include preprocessor directive to include the P7PIEXTH file in your program before making any calls to the procedures.
Procedure Calls Procedure Calls Table 3-2. P7 API Procedures (continued) Environment-Management Procedures Data-Transfer Procedures Purpose LOS_DT_FINISH_SEND_ Checks for the success or failure of a previously issued LOS_DT_SEND_ procedure. LOS_DT_FINISH_ RESULT Receives data from OSI?MHS and passes it to the client application. LOS_DT_SEND_ Binds the client application to an MS group, sends data to OSI/MHS, or unbinds the client application from an MS group.
LOS_CLOSE_ Procedure Calls Figure 3-1. Sample P7 API Procedure Call Description 1 2 status 4 = LOS_DT_SEND_ 3 ( sendFileNum, bufferPtr, maxBufferLen, dataType status ) ; returned value 5 long init 6 indicates the outcome of the call ... sendFileNum input int is an integer that identifies ... Legend 1 This indicates the type of value that the procedure returns. For the P7 API procedures, the variable name is always status . Appendix A gives the status values that can be returned.
LOS_DT_FINISH_RESULT_ Procedure Calls returned value status long int indicates the outcome of the call. A value of 0 indicates a successful call. For additional values, see Appendix B, “Return Codes.” input sendFileNum int specifies the file number of the currently open send file that is to be closed. This file number is returned from the call to LOS_OPEN_ . resultFileNum input int specifies the file number of the currently open result file that is to be closed.
LOS_DT_FINISH_RESULT_ Procedure Calls application. You should call this procedure when the file number returned from AWAITIOX is that of the result file. status = LOS_DT_FINISH_RESULT_ ( resultFileNum, bufferPtr, bufferLen, maxBufferLen, dataType, moreData); returned value status long int indicates the outcome of the call. A value of 0 indicates a successful call. For additional values, see Appendix B, “Return Codes.
LOS_DT_FINISH_RESULT_ Procedure Calls • • • • • • MESSAGE SUBMISSION operation MESSAGE SUBMISSION result or error PROBE SUBMISSION operation PROBE SUBMISSION result or error CANCEL DEFERRED operation CANCEL DEFERRED result or error REGISTER-MS operation REGISTER-MS result or error P-DATA information made up of the Remote Operations Invoke (ROIV) APDU for the SUBMISSION CONTROL argument. A Remote Operations Reject (RORJ) APDU if OSI/MHS is unable to interpret the ROIV APDU.
LOS_DT_FINISH_RESULT_ Procedure Calls specifies whether there is more data to be received from OSI/MHS. moreData can be ZMHS-VAL-DT-MORE-DATA or ZMHS-VAL-DT-NO-MORE-DATA. Considerations • • • The contents of bufferPtr varies from one call to LOS_DT_FINISH_RESULT_ to the next. Therefore, the validity of the data is guaranteed only until the next call to this procedure. To determine the size of the APDU being transferred from OSI/MHS, specify a buffer length of 0 bytes for the bufferLen parameter.
LOS_DT_FINISH_SEND_ Procedure Calls Example This example shows how to retrieve the result or error from the buffer used by the result file.
LOS_DT_SEND_ Procedure Calls Considerations • • After a send file number is returned from AWAITIOX, the client application must call this procedure before it can issue another call to LOS_DT_SEND_ . status can indicate that the application association has been aborted. In this case, call LOS_CLOSE_ , followed by LOS_OPEN_ to reestablish the session, then LOS_DT_SEND_ to bind to an MS group. Example This example shows how to check for completion on the send file.
LOS_DT_SEND_ Procedure Calls send plus 24 bytes. The first 24 bytes are reserved for control information and can be allocated using the DDL constant ZMHS-VAL-DT-DATA-OFFSET. The data in the buffer can be: • • An MSBIND argument, which is structured like the user data in an Application Control Service Element A-Associate Response Application Protocol Data Unit (ACSE AARE-APDU) as if ACSE were being used.
LOS_DT_SEND_ Procedure Calls moreData input int specifies whether there is more data to be sent. The values are ZMHS-VAL-DT-MORE-DATA and ZMHS-VAL-DT-NO-MORE-DATA. dataType input int specifies the data type of the data to be sent. dataType can be: ZMHS-VAL-DT-MS-BIND-ARG ZMHS-VAL-DT-MS-UNBIND-ARG ZMHS-VAL-DT-P-DATA For MSBIND and P-DATA, bufferPtr contains the associated data. For MSUNBIND, bufferPtr is empty.
LOS_INITIALIZE_ Procedure Calls A client application should not reuse an invoke ID until it either receives the response from the OSI/MHS subsystem or it issues an MSUNBIND operation. MSUNBIND should be issued only after responses have been received for all outstanding transactions. • A description of the content of the buffer can be found in 1988 CCITT recommendations as follows: • • • • X.
LOS_OPEN_ Procedure Calls status returned value long int indicates the outcome of the call. A value of 0 indicates a successful call. For additional values, see Appendix B, “Return Codes.” Considerations • • LOS_INITIALIZE_ allocates an area of extended memory to hold session-related data. If a client has open sessions with the P7 API when the program calls LOS_INITIALIZE_ , these sessions are closed and all session-related data is lost.
LOS_OPEN_ Procedure Calls specifies the fully qualified file name of the MHS manager process that controls the OSI/MHS subsystem with which the client application wants to communicate. The MHS manager process name must be the name of a named process. mhsMgrName has the format name-len followed by name where name-len is the length of the name, and name is the name of the MHS manager process.
LOS_OPEN_ Procedure Calls sendFileNum output extptr int * returns a file number to be used by the client application to send data to OSI/MHS. A return file number of -1 indicates that an error has occurred. You should call LOS_DT_FINISH_SEND_ when sendFileNum is returned to the client application from a call to AWAITIOX. resultFileNum output extptr int * returns a file number to be used by the client application to receive data from OSI/MHS.
Procedure Calls LOS_OPEN_ Example This example shows a call to LOS_OPEN_ that opens communication with the process $ZMHS, allocates two buffers, buf1 and buf2, and returns send and result file numbers to an array. /* GLOBALs */ #define MAX_CONNECTIONS ZMHS_VAL_LOUAPI_MAX_NUM_SESS static int sendFileNum[MAX_CONNECTIONS], resultFileNum[MAX_CONNECTIONS]; /* Local */ int connection; /* Logical connection to */ /* perform operation on */ mhsMgrName.name = (‘$’ ,‘z’, ‘m’, ‘h’, ‘s’); mhsMgrName.
Procedure Calls OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 3- 18 LOS_OPEN_
A DDL Definitions This appendix describes the data structures and external constants that you can use in parameters to the P7 API procedures. These structures and constants are expressed in the Data Definition Language (DDL). You receive the DDL in two forms: • • The equivalent of C code (in the file ZMHSC) is provided for you to include in your C program by using the #include directive.
External Constants DDL Definitions ZMHS-VAL-DT-xxx DATA-OFFSET MORE-DATA NO-MORE-DATA MS-BIND-ARG MS-UNBIND-ARG P-DATA MS-BIND-RESULT MS-BIND-ERROR MS-UNBIND-RESULT VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE VALUE 24 240 241 242 243 244 245 246 247 ZMHS-VAL-DT-DATA-OFFSET specifies a data offset from the beginning of the P7 API data blocks. These bytes are reserved for control information used by the P7 API during LOS_DT_SEND_ procedure calls.
External Constants DDL Definitions ZMHS-VAL-DT-MS-UNBIND-RESULT specifies the type of data being received with the LOS_DT_FINISH_RESULT_ procedure call. ZMHS-VAL-LOUAPI-xxx MAX-NUM-SESS MAX-MSG-SIZE MAX-DATA-SIZE 20 30024 30000 ZMHS-VAL-LOUAPI-MAX-NUM-SESS is the maximum number of sessions per client process. ZMHS-VAL-LOUAPI-MAX-MSG-SIZE specifies the maximum size of the message that can be transferred using LOS_DT_SEND_ and LOS_DT_FINISH_RESULT_ .
DDL Definitions External Constants OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 A- 4
B Return Codes This appendix provides the information you need to check the status of a procedure call and determine the cause of a failure. The following information is provided: • • A description of what to expect when checking the status parameter The values of return codes passed in the status parameter of each procedure Status Checking Each P7 API procedure returns a code in the status parameter that indicates the success or failure of the procedure call.
Return Code Values Return Codes 0 Cause. The operation was successfully completed. Effect. The application can proceed with the next step. Recovery. None is required. 103 ZMHS_VAL_EM_INVALID_WAIT_FLAG Cause. You specified a value other than ZMHS-VAL-EM-NO-WAIT for the waitFlag parameter of the LOS_OPEN_ procedure. The P7 API accepts only the NO-WAIT value. The subcode contains the value of the wait flag that you specified. Effect. The procedure is not performed. Recovery.
Return Code Values Return Codes Recovery. Try the procedure again with the correct file number. An invalid file number could indicate a problem with the storage of the file numbers. If you think you have the correct file number and still receive this error, check the code in your program. 107 ZMHS_VAL_EM_FILE_ERROR Cause. The P7 API encountered a file system error during a call to the LOS_OPEN_ procedure.
Return Code Values Return Codes 110 ZMHS_VAL_EM_SCP_ERR Cause. The P7 API cannot communicate with SCP. The problem could be an internal software error in OSI/MHS or corrupted data buffers used by the P7 API or other parts of the OSI/MHS subsystem. The subcode contains the value returned by a call to the Guardian FILEINFO procedure. (This call follows a call to WRITEREADX by the P7 API procedure that returned this error.) Effect. The procedure is not performed. Recovery.
Return Code Values Return Codes The subcode contains the error value. Effect. The procedure is not performed. Recovery. Check the versions of all files and objects to ensure compatibility by using the VPROC utility, the SCF VERSION MON command, or the SCF VERSION PROCESS command. 114 ZMHS_VAL_EM_NO_LOS_PROCESS Cause. A call to LOS_OPEN_ failed to locate an LO group with which to establish a session. This could be because: • • • There are no LO groups currently available.
Return Code Values Return Codes Recovery. See the Guardian Procedure Errors and Messages Manual for a description of the error given in the subcode. Follow the recovery procedure recommended in that manual. One possible cause might be that the selected LO group is not in the STARTED state. If the group is STOPPED, call LOS_CLOSE_ to terminate the session, then use LOS_OPEN_ to open a session with another group and try the operation again. 202 ZMHS_VAL_DT_WRITEREAD_FAILED Cause.
Return Code Values Return Codes Recovery. Change the value to a number between 1 and 30000 bytes. 30000 bytes is the maximum length that you can specify for the buffer. 205 ZMHS_VAL_DT_INVAL_MORE_DATA Cause. The value that you specified for the moreData parameter of the LOS_DT_SEND_ or the LOS_DT_FINISH_RESULT_ procedure was incorrect. The subcode contains the parameter value that you specified. Effect. The procedure is not performed. Recovery.
Return Code Values Return Codes 211 ZMHS_VAL_DT_INVAL_SEQ_NUM Cause. An internal P7 API/LO protocol error occurred. Either the sequence number of the block of data being sent by the P7 API does not match that expected by the LO group, or the sequence number of the block of data being sent by the LO group does not match that expected by the P7 API. The problem could be an internal software error in OSI/MHS or corrupted data buffers used by the P7 API or other parts of the OSI/MHS subsystem.
C Summary of P7 API Procedure Calls for the C Language This appendix provides a summary of the P7 API procedure calls for use in C language programs. For a description of each procedure and its arguments (parameters), see Section 3, “Procedure Calls.” For information about interpreting C language syntax, see Compaq’s C Reference Manual. An asterisk (*) indicates that the parameter is a pointer.
Summary of P7 API Procedure Calls for the C Language OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 C- 2
D Summary of P7 API Procedure Calls for the TAL Language This appendix provides a summary of the P7 API procedure calls for use in TAL-language programs. For a description of each procedure and its arguments (parameters), see Section 3, “Procedure Calls.” For information about interpreting TAL language syntax, see Compaq’s Transaction Application Language (TAL) Reference Manual.
Summary of P7 API Procedure Calls for the TAL Language OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 D- 2
E C Language Example Program This appendix presents a C language example program that shows how to call the Compaq OSI/MHS P7 Application Programmatic Interface (P7 API) procedures. The source code file for this example is provided as part of the OSI/MHS P7 API software. By default, it resides in the volume and subvolume $SYSTEM.ZMHS. Note. This example is subject to change in future releases. To use this program, you may need to change the OSI/MHS MHS manager name to reflect your environment.
C Language Example Program * The menu selections are ordered more or less in the order they should * be run you need to issue a second Await Completion after the Send Data * and the Send Unbind. The choices on the menu are: * * Choice 0 : This choice sends an MSBIND request to the LO group. * The program then waits for the send completion to occur. * * Choice 1 : Use this choice to wait for incoming data. The data is * usually an MSBIND or MSUNBIND response or other incoming * data.
C Language Example Program #define TRUE #define FALSE ((boolean)1) ((boolean)0) /* Define procedure name type for MHS manager name for LOS_OPEN_ */ typedef struct s_ProcName { short int length; char name[36]; }ProcName; /* Predeclaration of functions in this file */ void awaitCompletion (); void sendCompletion ( short int char fileNum, *buffer ); void resultCompletion ( short int fileNum, char *buffer ); void sendData ( char int int *buffer, connection, dataType); boolean isResultFile( int fileNu
C Language Example Program /* to send and receive ResultFileNum[MAX_CONNECTIONS]; /* messages on. */ */ long long RecvOffset; /* Current position in multiple receive /* of data buffers */ */ long long SendOffset; /* Offset into buffer to be sent out.
C Language Example Program scanf ("%d", &choice); printf (" \n"); /* execute the selection */ switch (choice) { case 0 : /* send MSBIND */ sendData (buffer, connection, ZMHS_VAL_DT_MS_BIND_ARG); awaitCompletion(); /* see if the send worked */ break; case 1 : /* await completion */ awaitCompletion(); /* check for responses to our requests */ break; case 2 : /* send P7 data */ /* Note: This choice was not tested with valid ASN.1 data.
C Language Example Program short short int int nchar; fileNum; /* Used in AWAITIOX call /* Used in AWAITIOX call */ */ /* Await completion on all files */ printf( "Awaiting completion on all files.
C Language Example Program long int long int int int ProcName maxDataLen; status; *buf1; *buf2; mhsMgrName; /* /* /* /* /* Length of received data Used in P7 API call Buffer used in LOS_OPEN call Buffer used in LOS_OPEN call Holds manager name for LOS_OPEN_ maxDataLen = ZMHS_VAL_LOUAPI_MAX_DATA_SIZE; /* Switch on the dataType of the user selection */ switch (dataType) { case ZMHS_VAL_DT_MS_BIND_ARG: /* * Fill in the MHSMGR name * * NOTE: The MHS manager name below may need to be changed for * your part
C Language Example Program } break; case ZMHS_VAL_DT_MS_UNBIND_ARG: /* * Fill in the buffer and set up data length. * After calling this function, the data starts at * ZMHS_VAL_DT_DATA_OFFSET in the buffer.
C Language Example Program SendOffset = ZMHS_VAL_LOUAPI_MAX_DATA_SIZE; } else { /* send all the data in one block */ SendLength = 0; printf ("calling LOS_DT_SEND_() with P DATA request\n"); status = LOS_DT_SEND_(SendFileNum[connection], (int *) buffer, dataLen, maxDataLen, ZMHS_VAL_DT_NO_MORE_DATA, ZMHS_VAL_DT_P_DATA); if (status != P7_SUCCESS) { /* Report the error, inform client and return */ statusError("LOS_DT_SEND_ failed", status); return; } } break; default: reportError("Invalid Data Type"); } retur
C Language Example Program * * * * */ 0020: 0030: 0040: 0050: 0B 44 45 56 45 4C 4F 50 4D 45 4E 54 83 04 4D 54 41 31 A5 08 80 06 55 41 4D 53 31 31 A6 09 13 07 4D 53 55 53 45 52 53 A2 08 04 06 55 41 4D 53 31 31 .DEVELOPMENT..MT A1....UAMS11.... MSUSERS....
C Language Example Program { long int short int long int int status; /* Used in P7 API call dataLen; /* Used in LOS_DT_SEND_ call maxDataLen = ZMHS_VAL_LOUAPI_MAX_DATA_SIZE; /* Length of received data resultFile; /* Holds fileNum to close for errors /* Check if send was successful */ printf ("calling LOS_DT_FINISH_SEND_() on send file\n"); status = LOS_DT_FINISH_SEND_(fileNum, (int *)buffer); if (status != P7_SUCCESS) { /* Report Error and aborted association to client */ statusError("LOS_DT_FINISH_SEND_
C Language Example Program } } return; } /* end sendCompletion */ #pragma page /***************************************************************************/ /* Function name: resultCompletion */ /* */ /* Arguments: fileNum */ /* buffer */ /* */ /* Description: This function processes a completion on the result file.*/ /* It receives the data from OSI/MHS and passes it to the */ /* client.
C Language Example Program data)\n"); status = LOS_DT_FINISH_RESULT_(fileNum, (long int *) &tmpBuffer, &bufLen, maxBufLen, &dataType, &moreData); if (status != P7_SUCCESS) { /* Report Error and aborted association to client */ statusError("LOS_DT_FINISH_RESULT_ failed",status); mapResultFileNum(fileNum, &sendFile); status = LOS_CLOSE_(sendFile, fileNum); return; } /* process result based on dataType */ switch (dataType) { case ZMHS_VAL_DT_MS_BIND_RESULT: /* copy the data received to a static buffer */ memc
C Language Example Program (size_t)bufLen); RecvOffset = 0; informClient(dataType, (zmhs_ddl_uapi_request_def *) RecvBufferPtr); } else { /* Copy the data received to a static buffer */ memcpy(&RecvBufferPtr[RecvOffset], tmpBuffer, (size_t)bufLen); informClient(dataType, (zmhs_ddl_uapi_request_def *) RecvBufferPtr); RecvOffset = RecvOffset + bufLen; } break; default: reportError("Invalid Data Type"); } return; } /* end resultCompletion */ /*******************************************************************
C Language Example Program /***************************************************************************/ void mapSendFileNum( int sendFile, int *resultFile) { int i; for ( i = 0 ; SendFileNum[i] != sendFile ; ++i) ; *resultFile = ResultFileNum[i]; return; } /***************************************************************************/ /* Function name: mapResultFileNum */ /* */ /* Arguments: resultFile */ /* sendFile */ /* */ /* Description: This function gets the corresponding send file */ /* number given
C Language Example Program (long)buffer->u_zresult_reply.zresult_reply.zbind_indication); printf("Bind Result : Error (%ld)\n", (long)buffer->u_zresult_reply.zresult_reply.zerror); break; case ZMHS_VAL_DT_MS_BIND_ERROR: printf("Bind Error : Sequence Number (%d)\n", buffer->u_zresult_reply.zresult_reply.zseq_number); printf("Bind Error : Continuation Marker (%ld)\n", (long)buffer>u_zresult_reply.zresult_reply.zcont_marker.zflag); printf("Bind Error : Length (%ld)\n", (long)buffer->u_zresult_reply.
C Language Example Program /* */ /***************************************************************************/ void reportFileError( int function, int error) { printf ("file Error : Function (%d) Error (%d) \n", function, error); return; } /***************************************************************************/ /* Function name: reportError */ /* */ /* Arguments: string */ /* */ /* Description: This function reports any error that occurred to */ /* the user.
C Language Example Program OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 E -18
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.
archive queue Glossary archive queue. A queue to which you can move an object from the input queue during a finish-transfer-in operation requested of the GPI. Typically, undecodable communications are placed on the archive queue for future examination using diagnostic procedures. See also communication. ASE (application service element).
attribute value Glossary attribute value. The data for specific instance of an attribute. For example, “US” is a possible value of an MH-T-COUNTRY-NAME attribute. 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.
Glossary command/response interface 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. In DSM programmatic interfaces, a definition (data declaration) used in several commands, responses, or event messages in an SPI interface to a subsystem. common name. In X.
context token Glossary 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. In DSM, those operations that affect or request information about the state or configuration of an object. See also event management. core services.
definition Glossary definition. A declaration provided by Compaq for use in applications that use a specific procedural interface, such as the APS or SPI procedures. Definitions are commonly provided in definition files. definition files. A set of files containing declarations for use in applications that use a specific procedural interface.
element Glossary 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). A part of DSM used to provide event collection, event logging, and event distribution facilities.
event Glossary 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. Events can be operational errors, notifications of limits exceeded, requests for action needed, and so on. event log. A file or set of files maintained by EMS to store event messages generated by subsystems. event management.
Glossary external tracing 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.
GPI (Gateway Programmatic Interface) Glossary GPI (Gateway Programmatic Interface). A service that provides X.400 access to proprietary messaging systems through Compaq OSI/MHS. GPI library. The GPI procedural interface. GPI service. The combined function of the GPI library and the GIP. group. A collection of one or more processes and databases that provide a defined set of services. GROUP object.
installation procedure Glossary installation procedure. The OSI/MHS procedure that creates a default edit file and prompts you to modify that file to fit your configuration requirements. installation subvolume. See ISV. interactive command. In DSM, a command given by a human operator rather than by a program. See also programmatic command. interface. In general, a set of rules by which a person, a program, or a device interacts with a hardware or software product.
layer Glossary 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. In OSI/MHS, a pair of OSI addresses that are configured for each MTA. A pair of OSI addresses is a set of local and remote address definitions in the MTA object representing an adjacent MTA. link retry.
mailbox count Glossary mailbox count. A “snapshot” of the recent activity in your mailbox: number of messages read, number of messages deleted, and so on. mailbox statistics. A historical report of the activity in your mailbox, starting with the previous RESET and continuing until the next RESET. 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 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 MHS manager. The MON object name identifies the MHS manager.
MTA object Glossary 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. 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.
nonsensitive command Glossary nonsensitive command. A DSM command that can be issued by any user or program having access to the target subsystem—that is, a command on which the subsystem imposes no further security restrictions. For Compaq data communications subsystems, the nonsensitive commands are usually information commands (commands that cannot change the state or configuration of objects). See also sensitive command. NonStop Kernel.
object management Glossary 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. A means to operate on messages and their elements as objects. object-name template.
Glossary OSI/MHS database 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. The Install process creates this subvolume as ZOSIMHS. OSI/MHS subsystem.
P2 message Glossary 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. P3 protocol. The X.400 message submission and delivery protocol, which defines a standard for the submission and delivery of messages and the interaction of UAs and MTAs. P7 protocol. The X.
port address Glossary interface that applications can use by making file-system procedure calls. The PAM subsystem implements, for LANs, the services of the Data Link Layer and layers below. PAM replaces the Tandem LAN Access Method (TLAM) for G06 and later releases. port address. For X25AM lines, the logical port number used to specify the address of the connection to the X.25 network. For TLAM lines, the address used by TLAM to specify the address of the connection to a LAN controller.
programmatic command Glossary programmatic command. In DSM, a command issued by a program rather than by a human operator. See also interactive command. programmatic interface. A mechanism by which a program can interact with other software. programmed operator. In DSM, a management application that performs functions that might otherwise be performed by a human operator. protocol.
remote MTA Glossary 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. report. A notification generated by the OSI/MHS subsystem that tells the user whether the message has been sent. request primitive. In OSI, a primitive issued when a service user wants the service to do some work.
ROSE (remote operations service element) Glossary ROSE (remote operations service element). An Application Layer service definition and protocol supporting interactive applications, implemented by the RS process in OSI/MHS. Examples of ROSE PDUs are: ROIV-APDU Invoke application protocol data unit RORJ-PDU Reject application protocol data unit ROER-APDU Error application protocol data unit RORS-APDU Response application protocol data unit route. A path through an X.
RTS (reliable transfer service) process Glossary 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. RUA (remote user agent). A user agent that submits and retrieves messages through a message store and resides on a system or device other than the system that provides the message store. See also LUA. SAP (service access point).
service Glossary service. A set of primitives (operations) that an OSI layer provides to the layer above it. The service defines what operations the layer can perform on behalf of its users, but not how these operations are implemented. A service relates to an interface between two layers, with the lower layer being the service provider and the upper layer being the service user. See also protocol. The GPI and P7 API are examples of services available to applications.
softdoc Glossary 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. A softdoc provides information about new product features and sometimes contains information not included in product manuals. SPI (Subsystem Programmatic Interface).
string segment Glossary string segment. A portion of a string value consisting of zero or more contiguous octets of its representation. subject. In event management, a device, process, or other named entity about which a given event message has information. subnetwork. In general, a network that participates in a larger network, possibly through the use of gateways or bridges. In OSI, one or more intermediate systems that provide relaying and through which end systems may establish network connections.
symbolic name Glossary names of which appear on the last part of the packing list. The SUT contains the DSVs for OSI/MHS and other products. symbolic name. In DSM programmatic interfaces, a name used in programs to refer to commonly used values, token codes, token maps, extensible structures, and other related variables for use in management programs. syntax. See attribute syntax. SYSGEN.
token code Glossary the SSGET procedure. A token has two parts: an identifying code, or token code, and a token value. In command and response messages, a token normally represents a parameter to a command, an item of information in a response, or control information 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.
TSAP (transport service access point) Glossary TSAP (transport service access point). A logical location between the Transport and Session Layers, through which transport services are made available to local users, and through which session services are made available to remote systems. TSEL (transport selector). An address between the Transport and Session Layers, through which connections are established and maintained.
working subvolume Glossary characters can appear: ? for a single character and * for zero, one, or more consecutive characters. In O/R name attributes, a single asterisk in place of the attribute indicates “not used.” In the X121-ADDR and NUMERIC-USER-ID attributes of the ADD APPL, ALTER APPL, ADD ROUTE, and ALTER ROUTE commands, a single asterisk (*) can substitute for the trailing characters of the attribute value, and the double asterisk (**) can substitute for the entire value.
$RECEIVE Glossary OSI/MHS P7 Application Programmatic Interface (P7 API) Manual—424825-001 Glossary -32
Index Numbers 1988 standards viii A Abbreviations Abbreviations-1 Abstract Syntax Notation One (ASN.1) viii Acronyms Abbreviations-1 APDU determining size 3-8 queuing 3-12 request APDU 3-11 response APDU 3-6 APPL object binding/unbinding 3-10 client application, defining 2-2 SUB-RELIABLE-TRANSFER attribute 2-9 Application associations maximum number allowed 1-4 Application programmatic interface 1-1 ASN.
E Index Data transfer (continued) checking send procedure results 3-9 retrieving buffer contents 3-5 submitting data 2-9, 3-10 unbinding from MS group 2-11 Data types declaration files 3-1 specifying data type sent in buffer 3-12 Data-transfer procedures defined 3-2 LOS_DT_FINISH_RESULT_ 3-5 LOS_DT_FINISH_SEND_ 3-9 LOS_DT_SEND_ 3-10 DDL files A-1 DDL constants for checking return code values B-1 for inclusion in your program A-1 Declaration files categorized 3-1 introduced 1-2 DELETE operation 2-11, 3-11
M Index LO group (continued) LO process 1-4 maximum number of associations allowed 1-4 opening 3-14 LO process, defined 1-4 Local user agent See Client application# 1-2 LOS_CLOSE_ 2-7, 3-4 LOS_DT_FINISH_RESULT_ 2-11, 3-5 LOS_DT_FINISH_SEND_ 2-9, 2-11, 3-9 LOS_DT_SEND_ 2-9, 2-11, 3-10 LOS_INITIALIZE_ 2-6, 3-13 LOS_OPEN_ 2-6, 3-14 M Message store access protocol.i.
Q Index P7PILIB file 2-12, 3-1 PROBE SUBMISSION operation 3-11 PROBE submission operation 2-9 Procedure calls declaration files 3-1 extended memory segmen 2-6 LOS_CLOSE_ 3-4 LOS_DT_FINISH_RESULT_ 3-5 LOS_DT_FINISH_SEND_ 3-9 LOS_DT_SEND_ 3-10 LOS_INITIALIZE_ 3-13 LOS_OPEN_ 3-14 naming conventions for 3-2 naming conventions for Naming conventions, P7 API procedures 3-2 return code values B-1 sequence of 2-3 status parameter values B-1 syntax presentation sample 3-3 Product subvolumes 3-1 Program structure,
T Index T TAL DDL declarations A-1 declaration files 3-1 syntax summary D-1 TMF 3-12 Transactions, number of outstanding 2-9 U Unbinding from an MS group 2-11 MSUNBIND request 2-11 unbinding from MS group 3-10 User agent See Client application# 1-1 User password (initiator credentials) 2-3 W Wait flag 3-15 Z ZMHSC file 3-1, A-1 ZMHSTAL file 3-1, A-1 Special Characters #include directive A-1 ?SOURCE directive A-1 OSI/MHS P7 Application Programmatic Interface (P7 API) Manual— 424825-001 Index -5
Index Special Characters OSI/MHS P7 Application Programmatic Interface (P7 API) Manual— 424825-001 Index -6
