ACSE/Presentation and ROSE Interface Programmer’s Guide Edition 4 32070-90032 HP9000 Networking 05/97 Printed in: United States © Copyright 1997 Hewlett-Packard Company. All rights reserved.
Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material. Warranty.
©copyright 1980, 1984, 1986 Novell, Inc. ©copyright 1986-1992 Sun Microsystems, Inc. ©copyright 1985-86, 1988 Massachusetts Institute of Technology. ©copyright 1989-93 The Open Software Foundation, Inc. ©copyright 1986 Digital Equipment Corporation. ©copyright 1990 Motorola, Inc.
Contents 1. APRI Overview Systems Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 ASN.1 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 File Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 What is the HP ACSE/Presentation and ROSE Interface . . . . . . . . . . .15 ACSE/Presentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Binding the Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Set up the Data Transfer Environment. . . . . . . . . . . . . . . . . . . . . . . . Request the Association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Confirm the Association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 36 37 38 Step 3. Exchanging Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Execution Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58 Connection Retry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Resource Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 System Maximums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 6. Other Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents A. ACSE/Presentation Reference Pages ACSE/Presentation Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing History The manual printing date and part number indicate its current edition. The printing date will change when a new edition is printed. Minor changes may be made at reprint without changing the printing date. The manual part number will change when extensive changes are made. Manual updates may be issued between editions to correct errors or document product changes. To ensure that you receive the updated or new editions, you should subscribe to the appropriate product support service.
In This Book This manual describes tools and procedures for using the ACSE/Presentation and ROSE application programmatic interface for OSI products. It is divided into three chapters, which provide the following information: Chapter 1 “APRI Overview” introduces the ACSE/Presentation and ROSE Interface and the supported standards. Chapter 2 “Supported ACSE/Presentation and ROSE Calls” contains descriptions of the programmatic calls supported by ACSE/Presentation and ROSE.
1 APRI Overview This chapter provides an overview of what the HP ACSE/Presentation and ROSE interface provides.
APRI Overview Systems Supported Systems Supported Access to the ACSE/Presentation and ROSE programmatic interface is provided with the HP OTS/9000 product on HP 9000 systems. ASN.1 Support If your application requires encoding/decoding abstract syntax notation one (ASN.1) data structures, you may need to use an ASN.1 compiler. Refer to your compiler's documentation for information about using ASN.1 in your application programs.
APRI Overview What is the HP ACSE/Presentation and ROSE Interface What is the HP ACSE/Presentation and ROSE Interface The ACSE/Presentation and ROSE interface (APRI) provides a programmatic interface to the Association Control Service Element (ACSE), Remote Operation Service Element (ROSE) and Presentation layer protocols over an OSI network. See Figure 1-1.
APRI Overview What is the HP ACSE/Presentation and ROSE Interface #define ap_errno _ap_errno() • Any multi-threaded application program, which also includes osi_lib.h, should include it after the threads-specific include files. • See the appropriate man page regarding thread-safe information about the various api’s.
APRI Overview Standards Supported Standards Supported The interface provided is based on the services defined in the ISO ACSE and Presentation Service Definitions (ISO 8649 and ISO 8822) and ROSE (ISO 9072). The HP OTS/9000 subset implementation of the ACSE/Presentation library interface is based on the UNIX International OSI ACSE/Presentation Library Interface specification draft dated October 25, 1990.
APRI Overview Standards Supported Figure 1-1 OSI MODEL - ACSE Presentation and ROSE APPLICATION PROCESS ACSE/Presentation & ROSE Interface Layer 7 ACSE ROSE Layer 6 PRESENTATION Layer 5 SESSION Layer 4 TRANSPORT Layer 3 NETWORK Layer 2 DATA LINK Layer 1 PHYSICAL PHYSICAL COMMUNICATION MEDIUM Limitations A subset of the standard has been implemented with the following limitations. For limitations on particular parameters, please refer to the manpages for the A/P and ROSE calls.
APRI Overview Standards Supported ACSE/Presentation: • The ap_restore(), ap_save() and ap_osic() calls are not supported. • The environment file (env_file) is not supported. The user's application environment is initialized using ap_init_env(), after which individual attributes can be set or changed using ap_set_env(). • Setting multiple environment variables with one call to ap_set_env() is not supported. • Retrieving (getting) multiple environment variables with one call to ap_get_env() is not supported.
APRI Overview Who Should Use This Manual Who Should Use This Manual This manual is provided for application programmers who need to use ACSE/Presentation and ROSE services. It is expected that the user of this manual is an experienced applications programmer with knowledge of the HP-UX operating system and programming environment, the X.
2 Supported ACSE/Presentation and ROSE Calls This chapter provides lists and brief descriptions of the supported ACSE/ Presentation and ROSE calls and primitives.
Supported ACSE/Presentation and ROSE Calls ACSE/Presentation Calls and Primitives ACSE/Presentation Calls and Primitives The primitives are grouped in the sequence used in an application. For example, the A_ASSOC_xxx primitives are listed in the order: A_ASSOC_REQ (request) A_ASSOC_IND (indication) A_ASSOC_RSP (response) A_ASSOC_CNF (confirmation) In the manpages entitled ap_intro and ap_env, you’ll find introductions to the A/P environment and the A/P library environment attributes.
Supported ACSE/Presentation and ROSE Calls ACSE/Presentation Calls and Primitives ap_init_env() ap_set_env() ap_get_env() • Send and receive service primitives which includes sending/receiving service requests and sending/receiving user data: ap_snd() ap_rcv() • Manage your applications: ap_error() ap_free() ap_poll() ACSE/Presentation Calls The following table lists the supported ACSE/Presentation function calls.
Supported ACSE/Presentation and ROSE Calls ACSE/Presentation Calls and Primitives A/P Call Description ap_rcv() Receive an A/P primitive over an association. User data may be associated with the primitive. ap_set_env() Set an attribute in the A/P environment. ap_snd() Send an A/P primitive over an association. User data may be associated with the primitive. ACSE/Presentation Primitives The following table lists the supported ACSE/Presentation layer service primitives.
Supported ACSE/Presentation and ROSE Calls ACSE/Presentation Calls and Primitives Primitives Description A_ASSOC_IND Used with ap_rcv() to indicate a request for association establishment. A_ASSOC_RSP Used with ap_snd() to respond to an association establishment request. A_ASSOC_CNF Used with ap_rcv() to confirm the establishment of an association. A_PABORT_REQ Used with ap_snd() to initiate a presentation layer provider abort. Provides the option of aborting when an invalid PDU is received.
Supported ACSE/Presentation and ROSE Calls ACSE/Presentation Calls and Primitives Primitives Description P_RESYNC_CNF Used with ap_rcv() to confirm a resynchronized request. P_SYNCMINOR_REQ Used with ap_snd to request the setting of a minor sync point. P_SMINOR_REQ P_SMINOR_IND Used with ap_rcv to indicate a request the to set a minor sync point.
Supported ACSE/Presentation and ROSE Calls ROSE Calls and Primitives ROSE Calls and Primitives The supported ROSE function calls and primitives are listed in Table 2-3 and in Table 2-4. Also refer to the man page RO_INTRO(5) for general information about ROSE. ROSE Calls ROSE only supports two calls as listed below. ROSE is used to provide ROSE provider services to an application using the ACSE/Presentation interface. Table 2-3 Rose Calls ROSE Calls Description ro_bind() Enable ROSE provider.
Supported ACSE/Presentation and ROSE Calls ROSE Calls and Primitives Primitives RO_REJECTP_IND Description ROSE provider rejection indication. RO_REJ_P_IND RO_REJECTU_REQ ROSE user invocation rejection request. RO_REJ_U_REQ RO_REJECTU_IND RO_REJ_U_IND RO_RESULT_REQ RO_RESULTREQ RO_RESULT_IND RO_RESULTIND 28 ROSE user invocation rejection indication. Positive remote operation results request. Positive remote operation results indication.
3 Using ACSE/Presentation This chapter provides a sample session using ACSE/Presentation between two processes in synchronous mode.
Using ACSE/Presentation Synchronous ACSE/Presentation Synchronous ACSE/Presentation ACSE/Presentation calls block until the call is complete in synchronous mode. See the section, “Using Synchronous vs. Asynchronous Mode” in chapter 4 for more information. In order to use the ACSE/Presentation service, the processes do the following: 1. Create a communication endpoint. 2. Establish an association that requires: a. Initializing the ACSE/Presentation environment. b.
Using ACSE/Presentation Summary of Calls Summary of Calls A summary of the ACSE/Presentation calls are described in the following sections. Table 3-1 ACSE/Presentation Call Summary Process A Process B ap_open() ap_open() ap_init_env() ap_init_env() ap_set_env() (*initiator*) ap_set_env() (*responder*) ap_set_env() (*p-address*) ap_set_env() (*p-address*) ap_set_env() (*B's p-address*) ap_set_env() (*appl. context*) ap_set_env() (*PCDL*) ap_snd() (*assoc. req.
Using ACSE/Presentation Summary of Calls Process A Process B ap_rcv() (*rel. ind.*) ap_poll() <====== ap_snd() (*rel. rsp*) ap_rcv() (*rel. cnf.
Using ACSE/Presentation Step 1: Create a Communication Endpoint Step 1: Create a Communication Endpoint Process A and Process B must both create communication endpoints as shown in Figure 3-1, using the call ap_open(). A communication endpoint is a file descriptor (fd) which is returned on successful completion of the ap_open() call. The process uses the file descriptor in all subsequent A/P calls.
Using ACSE/Presentation Step 2: Establish an Association Step 2: Establish an Association The steps to establish an association are described below. Initialize the A/P Environment To use the A/P services, each process must initialize the ACSE/Presentation environment by calling ap_init_env(). (See Figure 3-2.) The ap_init_env() call allocates memory for the environment attributes, and sets the attributes to default values. (See the AP_ENV Table of Attributes in Appendix A for more information.
Using ACSE/Presentation Step 2: Establish an Association Establish Initiator and Responder Roles Process A and Process B establish initiator and responder roles using the attribute, AP_ROLE_ALLOWED in a call to ap_set_env(). In this example, Process A is the initiator, and Process B is the responder. (See Figure 3-3.
Using ACSE/Presentation Step 2: Establish an Association APRI also supports the binding of the local presentation address without specifying a network address. This allows a single responder to receive association indications for any of the subnetworks configured on an OTS/ 9000 system. To use this feature, when setting the local address through the AP_BIND_PADDR environment attribute, set the n_nsaps field of the ap_paddr_t structure to zero.
Using ACSE/Presentation Step 2: Establish an Association Process A calls ap_set_env() using the AP_CNTX_NAME attribute to identify the application context name. Process A then calls ap_set_env() using the AP_PCDL attribute to propose transfer syntaxes for each proposed abstract syntax that will be used for data transfer between Process A and B.
Using ACSE/Presentation Step 2: Establish an Association Figure 3-6 Request Association Process A Process B AP Environment A AP Environment B remote p-address, appl. context name pres. context def. list Initiator ap_snd() Communication Endpoint A request assoc. Responder ap_poll() Communication Endpoint B (listening) Confirm the Association When a request has been received by checking the ap_poll() events parameter, Process B calls ap_rcv() and receives A_ASSOC_IND.
Using ACSE/Presentation Step 2: Establish an Association Process B can reject the connection if the proposed transfer syntax is not supported by setting the res field in structure ap_cdrl_t to USER_REJ or PROV_REJ and prov_rsn is the reason for the reject. If the process cannot accept the association request for other reasons, the process sets the reason using the A_ASSOC_RSP primitive.
Using ACSE/Presentation Step 3. Exchanging Data Step 3. Exchanging Data Once an association is established, processes can send and receive control data (primitives) and user data. It is the responsibility of the process to encode and decode data with the selected transfer syntax. For complex data types, you can choose to use an ASN.1 compiler to assist in the creation of these routines.
Using ACSE/Presentation Step 3.
Using ACSE/Presentation Step 4: Release the Association Step 4: Release the Association Processes must cooperate to ensure that no data is lost when the association is released. This can be accomplished by requesting a release, accepting the release, then terminating the association. Requesting the Release After Process A has completed sending user data, it sends a release request to Process B using ap_snd() with the A_RELEASE_REQ primitive (Figure 9).
Using ACSE/Presentation Step 4: Release the Association The process closes the association until it receives the positive release response from Process B. Process A monitors events with ap_poll() and receives the response by calling ap_rcv(). If an association is released abnormally, for example, if a lower layer problem occurs, a provider abort (A_PABORT_IND primitive) may be received.
Using ACSE/Presentation Step 5: Closing the Communication Endpoint Step 5: Closing the Communication Endpoint Finally, both processes use ap_close() to close down the communication endpoint (file descriptor) and A/P environment resources (see Figure 3-11). If the association is still alive when ap_close() is invoked, the association will be aborted by the provider before the communication endpoint is released.
4 Programming Guide This chapter provides information to assist you in writing and executing applications using the ACSE/Presentation (A/P) interface.
Programming Guide Summary of Programming Tasks Summary of Programming Tasks The following list summarizes the tasks you need to perform in order to successfully create and execute your programs. These tasks are discussed in more detail in the following sections. 1. Prepare system. Make sure HP OTS/9000 h as been installed, configured, and started successfully. (See the Installing and Administering OSI Transport Services manual for information.) 2. Manage the A/P environment.
Programming Guide Summary of Programming Tasks 5. Decide if multiple associations need to be supported. The process accepting multiple connections needs to create additional communication endpoints and instances of the A/P environment. Review the paragraphs describing: execution mode, connection retry, and maximum number of connections supported (system, processes, and other applications). 6.
Programming Guide 1. Prepare the System 1. Prepare the System Before you use the ACSE/Presentation interfaces, make sure that the following has been done: • Verify HP OTS/9000 h as been installed correctly. • Check that the presentation addresses, in particular, the local NSAP(s) used by the ACSE/Presentation applications that have been configured in the OTS configuration file. • Verify that HP OTS/9000 h as been started either manually using osiadmin or at start-up time.
Programming Guide 2. Manage the A/P Environment 2. Manage the A/P Environment The ACSE/Presentation environment contains the necessary information to establish and maintain an association. The primitives used to identify this information are called attributes. See Appendix A, “AP_ENV Table of Attributes” which describes the states and whether or not particular attributes can be written to or read from.
Programming Guide 2. Manage the A/P Environment On the other hand, when the connection indication is received by the other process, it is established as the responder, and can no longer issue a connection request. The AP_ROLE_CURRENT is automatically set to AP_RESPONDER.
Programming Guide 2. Manage the A/P Environment ap_set_env(fd,AP_BIND_PADDR,paddress) Note that rebinding the presentation address is not supported in this release. Binding can only be done in the AP_UNBOUND state.
Programming Guide 2. Manage the A/P Environment Application Contexts (AP_CNTX_NAME) Associations must negotiate the application contexts used. The initiator proposes a service or services to run, and the responder must reply to accept or reject the context. This is a mandatory parameter in the OSI ACSE layer. For more information, refer to the OSI ACSE standard (ISO 8649, 8650). Presentation Contexts (AP_PCDL) The presentation context definition list (PCDL) is a list of presentation contexts.
Programming Guide 2. Manage the A/P Environment • Isolate the allocations and freeing of memory passed to the A/P library to a single function. For example: void *ubuf_ptr; user_get_osi_buf (&ubuf_ptr, len,”data to put in ubuf”); ap_snd (.., ubuf_ptr); • Do not statically initialize a cdata structure. For example, do not use the statement: a_assoc_req_env_t peer_application = {...}; • Do not use the udata_length part of the cdata parameter for inbound indications.
Programming Guide 3. Managing Data 3. Managing Data ACSE/Presentation (A/P) defines two types of data: control data and user data. Control data (cdata) is associated with the primitives and its content is specific to each primitive. User data (ubuf) is managed by the application and is defined by the context and transfer syntax selected. Control Data Control data is associated with the supported ACSE/Presentation primitives and is managed by the A/P library.
Programming Guide 3. Managing Data 1) First ap_snd() set AP_MORE, and send data 2) Additional ap_snd()'s set AP_MORE, and send data 3) Last ap_snd() re-set AP_MORE, and send last data When receiving data, the AP_MORE bit is set by the A/P library if the receiving ubuf is not large enough, or if a partial primitive was received. In either case, the application must continue to invoke ap_rcv() to receive the remainder of the data. It is recommended that after each ap_rcv() call, the sptype is checked.
Programming Guide 4. Using Synchronous vs. Asynchronous Mode 4. Using Synchronous vs. Asynchronous Mode ACSE/Presentation supports both synchronous and asynchronous mode execution of calls. In synchronous mode, an ACSE/Presentation call blocks until the call can be completed. While blocked, no other tasks can be performed. Synchronous mode is the default. In asynchronous mode, an ACSE/Presentation call is not blocked (except under kernel resource shortages).
Programming Guide 4. Using Synchronous vs. Asynchronous Mode If ap_rcv() is called in asynchronous mode, data is read from the communication endpoint until either: • the entire primitive is received • the ubuf argument buffer is full • no more user data is available. In the second case, the AP_MORE bit is set in the flags parameter of ap_rcv(). If the AP_MORE bit is set, a primitive was partially received.
Programming Guide 5. Managing Multiple Connections 5. Managing Multiple Connections Before writing an application with multiple connections, you may need to consider the following items: • Execution mode • Connection retry • Resource constraints Execution Mode For using multiple connections, asynchronous mode is recommended.
Programming Guide 5. Managing Multiple Connections packets and is waiting for the release indication (A_RELEASE_IND) while endpoint D is in AP_IDLE state waiting for the connection indication (A_ASSOC_IND). Figure 4-1 Multiple Connections Scenario Initiator Process Responder Process ==================================================== servicing servicing Conn B .sent A_ASSOC_REQ .waiting for A_ASSOC_CNF Conn C .sent all data packets .waiting for A_RELEASE_IND Conn A .sent all data packets .
Programming Guide 5. Managing Multiple Connections Connection Retry When there is a resource shortage, ap_snd() may return AP_AGAIN. The application should re-send the same primitive as outlined in the ap_snd() manpage. NOTE In the case of a connection request (A_ASSOC_REQ), if a resource shortage occurs in the OTS stack, a reject may be received as a A_PABORT_IND or A_ABORT_IND. A_PABORT_IND indicates a shortage of memory in the OTS stack while trying to establish a connection.
Programming Guide 5. Managing Multiple Connections Note that if an ACSE/Presentation call (such as ap_open()) fails because of temporary memory shortage, the application may want to retry the same call later. System Maximums OTS supports up to 4096 virtual circuit (VC) connections at the transport and network layer (X.25 CONS). If applications such as X.400 or FTAM are also in use, note that each session access connection also uses a transport connection.
Programming Guide 6. Other Tasks 6. Other Tasks Other items to consider in developing A/P applications include: • File descriptors • Signal handling • Error checking File Descriptors Communication endpoints for ACSE/Presentation applications are HP-UX file descriptors. Because of unpredictable results, HP recommends you do not use HP-UX file system calls such as exec(2), dup(2), read(2), write(2), ioctl(2), or select(2) with HP OTS/9000 A CSE/Presentation file descriptors.
Programming Guide 6. Other Tasks Signal handlers can be written to capture signals and exit, or to prevent signals from interrupting critical call sequences. Error Checking Routines Along with processing signals, ACSE/Presentation applications need to check for return codes from calls and particular error conditions that are returned. Error conditions related to ACSE/Presentation as well as other protocol errors can be returned.
Programming Guide 7. Before Running ACSE/Presentation Applications 7. Before Running ACSE/Presentation Applications In order to run ACSE/Presentation applications between two processes or systems, make sure: • your local and remote systems have the correct configuration such as local and destination NSAPs • that the OTS stack has been started successfully on both your local and remote systems • you start your responder process first.
Programming Guide ACSE/Presentation Example ACSE/Presentation Example Sample programs are included online in the /opt/ots/apli/demo directory. You’ll also find: • A readme file describing how the programs work. • Header files included by the programs in the incl subdirectory. • Functions specific to the Marben ASN.1 compiler and run-time library to build, encode, decode, and free PDUs or C data structures generated by the compiler are included in the file: asn1_if.c.
Programming Guide Program using ROSE Program using ROSE Additional programs are included online in /opt/ots/rose/demo which exercise the ROSE library functions and provide an example using ROSE API tracing. Multi-threaded sample programs with similar functionality are also included online in the /opt/ots/rose/demo/threads_demo directory. These programs use Kernel Threads. Refer to the online README f ile for more information.
5 Troubleshooting Your Application This chapter describes API tracing for ACSE/Presentation followed by API tracing for ROSE.
Troubleshooting Your Application Using A/P API Tracing Using A/P API Tracing You enable tracing in your application program and the tracing output is printed to a trace file. Different levels of tracing are provided with the trace facility. For example, you can trace procedure entry and exits, error conditions, or both. A/P API Tracing Using Environmental Variables A/P API has been enhanced to allow control of tracing via environment variables.
Troubleshooting Your Application Using A/P API Tracing environment variables on the first valid APRI call (always ap_open) and then set the global API trace variables according to the value of the environment variables. If no environment variables are present, then no API tracing takes place.
Troubleshooting Your Application Using A/P API Tracing AP_TRACE_MAX_UDATA:. The maximum amount of user data (in bytes) that will be displayed when parameters are displayed. Default = 16. Tracing Using Global Variables A/P API tracing is controlled by three global variables. The variables are described below: ap_trace An integer value which constitutes a bitmask to control the level of tracing performed. By default this mask is 0. ap_trace_fp A pointer to a UNIX file to receive the tracing output.
Troubleshooting Your Application Using A/P API Tracing API_TR_ENTRY_EXIT Traces procedure entry and exit. No parameter information is displayed. This is useful if you are only interested in seeing what A/P calls your program is making. Note that this trace is automatically generated if you use API_TR_INPUT, API_TR_OUTPUT, or API_TR_INT_ENTRY_EXIT. API_TR_INPUT Provides traces of A/P function call input parameters. This is useful if you want to verify that A/P is actually receiving the values you expect.
Troubleshooting Your Application Using A/P API Tracing 2. Within your program, enable tracing and select the level of tracing you want by modifying the value of the ap_trace variable. For example, to enable procedure tracing, input parameters tracing, output parameters tracing, and error tracing enter the statement: ap_trace = API_TR_ENTRY_EXIT | API_TR_INPUT | API_TR_OUTPUT|API_TR_INT_ERROR; 3.
Troubleshooting Your Application Using A/P API Tracing 15:53:38 <- ap_set_env() = 0 attr = AP_CNTX_NAME val->len = 4 val->buf = (4/4) 52 01 00 04 R.... • The amount of data displayed is based on the value set for ap_trace_max_udata. For example, if ap_trace_max_udata is set to 16, only the first 16 bytes are displayed as shown below: val->sad.buf = (16/22) 06 69 5F 73 73 65 6C 06 69 5F 74 73 65 6C 07 48.i_ssel.i_tsel.H The item “(16/22)” indicates that 16 of the 22 bytes of data output is displayed.
Troubleshooting Your Application Using A/P API Tracing >>> thread-id = 6 >>> > pathname = /dev/osipi > oflags = 0x0 <<< thread-id = 6 <<< >>> thread-id = 7 >>> > pathname = /dev/osipi > oflags = 0x0 <<< thread-id = 7 <<< The line >>> thread-id = 5 >>> denotes that the lines following it have been output by the thread with the thread-id 5. Also, the line <<< thread-id = 5 <<< denotes the end of trace output from the thread with thread-id 5.
Troubleshooting Your Application Using ROSE API Tracing Using ROSE API Tracing Tracing is enabled in your application program and the tracing output is printed to a trace file. Different levels of tracing are provided with the trace facility. For example, you can trace procedure entry and exits, error conditions, or both. ROSE tracing has been implemented to be consistent with ACSE/Presentation tracing.
Troubleshooting Your Application Using ROSE API Tracing AP_TRACE_FILE: The name of the file that is to receive tracing results. Default = stderr. AP_TRACE_MAX_UDATA: The maximum amount of user data (in bytes) that will be displayed when parameters are displayed. Default = 16. Tracing Using Global Variables ROSE API tracing is controlled by three global variables.
Troubleshooting Your Application Using ROSE API Tracing Table 5-2 ROSE Tracing Types API_TR_ENTRY_EXIT Traces procedure entry and exit. No parameter information is displayed. This is useful if you are only interested in seeing what ROSE calls your program is making. Note that this trace is automatically generated if you use API_TR_INPUT, API_TR_OUTPUT, or API_TR_INT_ENTRY_EXIT. API_TR_INPUT Provides traces of ROSE function call input parameters.
Troubleshooting Your Application Using ROSE API Tracing 2. Within your program, enable tracing and select the level of tracing you want by modifying the value of the rose_trace variable. For example, to enable procedure tracing, input parameters tracing, output parameters tracing and error tracing, enter the statement: rose_trace = API_TR_ENTRY_EXIT|API_TR_INPUT|API_TR_OUTPUT|API_TR_I NT_ERROR; 3.
Troubleshooting Your Application Using ROSE API Tracing • The amount of data displayed is based on the value set for rose_trace_max_udata. For example, if rose_trace_max_udata is set to 16, only the first 16 bytes are displayed. Tracing in Multi-threaded Applications The format of the trace output in ROSE API traces in multi-threaded applications is consistent with the format described for A/P API traces in similar applications.
Troubleshooting Your Application Using ROSE API Tracing 80 Chapter 5
A ACSE/Presentation Reference Pages This appendix includes a list of the supported ACSE/Presentation attributes and a glossary of terms 81
ACSE/Presentation Primitives Table A-1 AP_ENV Table of Attributes Name of attribute/ Data Type Purpose AP_ACSE_AVAIL Bitmask indicating available versions of the ISO ACSE protocol AP_ACSE_SEL Bitmask indicating which version of the ISO ACSE protocol is currently selected AP_BIND_PADDR Writable states (value of AP_STATE attribute) or'd bits: AP_ACSEVER1 bit values: AP_ACSEVER1 always never unsigned long or'd bits: bit values: always only in states: AP_ACSEVER1 AP_ACSEVER1 AP_UNBOUND AP_IDLE
Name of attribute/ Data Type Purpose AP_CLD_AEQ any_t Default value of attribute None Called application entity qualifier AP_CLD_APID long any_t None ap_conn _id_t None Session connection identifier proposed by the associationresponder long AP_CLG_AEQ Calling application entity qualifier Any allowed by the C type always any_t Any allowed by the C type always ap_conn_id_t long any_t None Any allowed by the C type any_t only in states: AP_UNBOUND AP_IDLE only in states: AP_UNBOUND AP_IDLE
Name of attribute/ Data Type Purpose AP_CLG_APID long Default value of attribute long any_t None Calling application process title AP_CLG_CONN_ID ap_conn _id_t None Session connection identifier proposed by the association-initiator AP_CNTX_NAME objid_t N.A. Application context for the association Defined context set (This attribute consolidates information conveyed by the AP_PCDL and AP_PCDRL attributes.) ap_dcs_t N.A.
Name of attribute/ Data Type Purpose AP_DPCN Default value of attribute Any allowed by the C type never ap_dcn_t * never long AP_DPCR_NOVAL one of: never never always only in states AP_DPCR_NOVAL AP_ACCEPT * AP_USER_REJ * AP_PROV_REJ * unsigned Initial synchronization long point serial number AP_INIT_SYNC_PT AP_MIN_SYNCP AP_LIB_SEL Bitmask indicating which version of the A/ P-Library is currently selected AP_MIN_SYNCP to AP_MAX_SYNCP(999999) AP_UNBOUND AP_IDLE AP_WASSOCrsp_ ASS OCind N.A.
Name of attribute/ Data Type Purpose AP_MODE_AVAIL Specifies the modes in which the ACSE services may operate AP_MODE_SEL Specifies the mode in which the ACSE services will operate for this association AP_MSTATE State of AP_MORE bits (both send and receive) AP_PCDL unsigned long Default value of attribute or'd bits: bit values: AP_NORMAL_MODE AP_X410_MODE AP_NORMAL_MODE AP_X410_MODE or'd bits: bit values: AP_NORMAL_MODE AP_NORMAL_MODE AP_X410_MODE unsigned long or'd bits: NULL bit values:
Name of attribute/ Data Type Purpose AP_PFU_SEL Bitmask indicating which Presentation Layer functional units are currently selected AP_PRES_AVAIL Bitmask indicating available versions of the ISO Presentation Layer protocol AP_PRES_SEL Bitmask indicating which version of the ISO Presentation Layer protocol is currently selected Writable states (value of AP_STATE attribute) unsigned long or'd bits: NULL unsigned long or'd bits: bit values: AP_PRESVER1 AP_PRESVER1 or'd bits: bit values: AP_PRESV
Name of attribute/ Data Type Purpose AP_ROLE_CURRENT Indicates whether the library user is the association-initiator or the associationresponder for the current association AP_RSP_AEID unsigned long long Default value of attribute None any_t None long Any allowed by the C type always any_t AP_RSP_APID_NOVAL Any allowed by the C type always None never AP_UNBOUND AP_IDLE long any_t Writable states (value of AP_STATE attribute) Any allowed by the C type always any_t only in states AP_UNBOUND
Name of attribute/ Data Type Purpose AP_SESS_AVAIL Bitmask indicating available versions of the ISO Session Layer protocol unsigned long unsigned long Bitmask indicating whether certain optional capabilities of the session layer are supported by the underlying protocol provider AP_SESS_OPT_AVAIL AP_SESS_SEL or'd bits: bit values: AP_SESSVER1 AP_SESSVER2 AP_SESSVER1 AP_SESSVER2 or'd bit bit values: AP_UCBC AP_UCBC Readable states (value of AP_STATE attribute) Writable states (value of AP_STATE
Name of attribute/ Data Type Purpose AP_SFU_AVAIL Bitmark indicating which Session Layer functional units are available AP_SFU_SEL Bitmark indicating which Session Layer functional units are currently selected unsigned long unsigned long Default value of attribute Values legal for this attribute (* = not supported by current release) or'd bits: AP_SESS_DUPLEX AP_SESS_MINORSYNC AP_SESS_RESYNC AP_SESS_NEGREL AP_SESS_HALFDUPLEX* AP_SESS_DUPLEX AP_SESS_XDATA * AP_SESS_MINORSYNC AP_SESS_MAJORSYNC * AP_
Name of attribute/ Data Type Purpose AP_STATE Current state of the A/P- Library Interface Bitmark indicating characteristics of the connection endpoint supporting the A/PLibrary unsigned long AP_UNBOUND unsigned long None one of: Readable states (value of AP_STATE attribute) Writable states (value of AP_STATE attribute) always never always always AP_UNBOUND AP_DATAXFER AP_WASSOCrsp_ASSOCind AP_WASSOCcnf_ASSOCreq AP_WRELrsp_RELind AP_WRELcnf_RELreq AP_WRESYNrsp_RESYNind AP_WRESYNcnf_RESYNreq A
Name of attribute/ Data Type Purpose AP_TOKENS_AVAIL Bitmark indicating which session tokens are available AP_TOKENS_OWNED Bitmark indicating which tokens the user currently controls Default value of attribute unsigned long or'd bits: NULL unsigned long N.A.
Table A-2 Primitive A_ABORT_IND AP_RCV Table of Attributes This primitive valid in states all except: Ap_env attribute that must be set May change attributes Next state (values of AP_STATE attribute) none AP_STATE AP_IDLE AP_BIND_PA DDR AP_ACSE_SEL AP_CLD_AEID AP_CLD_AEQ AP_CLD_APID AP_CLD_APT AP_CLG_AEID AP_CLG_AEQ AP_CLG_APID AP_CLG_APT AP_CLG_CONN_ID AP_CNTX_NAME AP_INIT_SYNC_PT AP_LCL_PADDR AP_MODE_SEL AP_PCDL AP_PFU_SEL AP_PRES_SEL AP_REM_PADDR AP_ROLE_CURRENT AP_SESS_SEL AP_SFU_SEL AP_STA
Primitive This primitive valid in states Ap_env attribute that must be set May change attributes Next state (values of AP_STATE attribute) A_ASSOC_CNF AP_WASSOCcnf_ASSOCreq none AP_ACSE_SEL AP_CLD_CONN_ID AP_CNTX_NAME AP_DCS AP_INIT_SYNC_PT AP_PFU_SEL AP_PCDRL AP_PRES_SEL AP_REM_PADDR AP_SESS_SEL AP_SFU_SEL AP_STATE AP_TOKENS_AVAIL AP_TOKENS_OWNED (AP_IDLE, AP_DATAXFER) A_PABORT_IND all except: none AP_STATE AP_IDLE AP_UNBOUND AP_IDLE AP_DATAXFER AP_WRELcnf_RELreq none AP_STATE AP_WRELrsp_
Primitive This primitive valid in states Ap_env attribute that must be set May change attributes Next state (values of AP_STATE attribute) AP_WRESYNcnf_RESYNreq none AP_STATE AP_TOKENS_OWNED AP_DATAXFER P_SYNCMINOR_IND AP_DATA_XFER none none no state change P_SYNCMINOR_CNF AP_DATA_XFER AP_WRELcnf_RELreq AP_WSYNCMAcnf_SYNCMAreq AP_WACTEcnf_ACTreq none none no state change P_TOKENGIVE_IND AP_DATAXFER AP_WSYNCMAcnf_SYNCMAreq AP_WACTEcnf_ACTEreq AP_WSYNCHMArsp_ SYNCHMAind AP_WACTErsp_ACTEind
Primitive This primitive valid in states Ap_env attribute that must be set May change attributes Next state (values of AP_STATE attribute) RO_REJECTU_IND AP_DATAXFER AP_WRELcnf_RELreq AP_WSYNCMAcnf_SYNCMAreq AP_WACTEcnf_ACTEreq none none no state change RO_RESULT_IND AP_DATAXFER AP_WRELcnf_RELreq AP_WSYNCMAcnf_SYNCMAreq AP_WACTEcnf_ACTEreq none none no state change ACSE/Presentation Reference Pages ACSE/Presentation Primitives 96
Table A-3 Primitive A_ABORT_REQ AP_SND Table of Attributes This primitive, valid in states all except: Ap_env attributes that may be set (must be set in BOLD) May change attributes Next state (values of AP_STATE attribute) none AP_STATE AP_IDLE AP_UNBOUND AP_IDLE AP_IDLE AP_BIND_PADDR AP_CNTX_NAME AP_LCL_PADDR AP_REM_PADDR AP_LIB_SEL AP_ACSE_SEL AP_ROLE_ALLOWEDAP_ CLD_AEID AP_CLD_AEQ AP_CLD_APID AP_CLD_APT AP_CLG_AEID AP_CLG_AEQ AP_CLG_APID AP_CLG_APT AP_CLG_CONN_ID AP_MODE_SEL AP_PCDL AP_PFU_S
Primitive A_PABORT_REQ This primitive, valid in states all except: Ap_env attributes that may be set (must be set in BOLD) May change attributes Next state (values of AP_STATE attribute) none AP_STATE AP_IDLE AP_UNBOUND AP_IDLE AP_DATAXFER none AP_STATE AP_WRELcnf_RELreq A_RELEASE_RSP AP_WRELrsp_RELind AP_WRELrsp_RELind_init none AP_STATE (AP_IDLE or AP_DATAXFER) AP_WRELcnf_RELreq P_DATA_REQ AP_DATAXFER none AP_WRELrsp_RELind AP_WSYNCHMArsp_SYNCMAind AP_WACTErsp_ACTEind none no state c
Primitive This primitive, valid in states Ap_env attributes that may be set (must be set in BOLD) P_TOKENGIVE_REQ AP_DATAXFER none AP_WSYNCHMAcnf_SYNCMAreq AP_WACTEcnf_ACTEreq AP_WSYNCMArsp_SYNCMAind AP_WACTErsp_ACTEind AP_WRBCOVERYreq P_TOKEN PLEASE_R EQ AP_DATAXFER AP_WRELrsp_RELind AP_WSYNCMArsp_SYNCMAind AP_WACTErsp_ACTEind AP_WCDATArsp_CDATAind May change attributes Next state (values of AP_STATE attribute) no state change no state change no state change no state change no state change (no stat
ACSE/Presentation Reference Pages ACSE/Presentation Primitives 100 Appendix A
Glossary Application Layer Layer 7 of the OSI model; the user interface to network services and applications that provides services to directly support users. provided by ACSE, Presentation and remote operation service element (ROSE). ACSE Association Control Service Element. The service element in the OSI Application layer responsible for association establishment and release. ASN.1 Abstract Syntax Notation One. The OSI description language used to define data types.
Glossary Common Management Information Protocol. the OSI network management protocol. Common Element. The OSI application layer service element for network management. conformance adherence to a product specification; along with interoperability, a defining characteristic of an OSIcompatible product. Connectionless network service. The layer 3 network layer that provides datagrams to transmit data. Connection oriented network service.
Glossary EDI Electronic Data Interchange; an emerging Application Layer standard for the electronic exchange of business data. ES End system. EWOS European Workshop on Open Systems. communicate. Also known as functional standard or standard profiles. international standard (IS) a networking standard that has been approved by ISO or CCITT. FDDI Fiber Distributed Data Interface; a standard for a local area network that uses fiber optics and operates at 100 Mbps.
Glossary has defined the NSAP format for a given NSAP. It is partitioned into two parts, the authority format identifier (AFI) and the initial domain identifier (IDI). IDP spaces are managed by organizations such as AFNOR, ANSI and NIST. ISDN See Integrated Services Digital Network IS-IS Protocol Intermediate system to intermediate system protocol. An evolving ISO protocol standard to provide automatic routing between intermediate systems.
Glossary ODA Office Document Architecture; a developing standard that enables text, graphics and facsimile, in different document formats, to be moved over a multivendor network. OSI Open Systems Interconnection; the name used to describe a set of data communications standards which have been agreed upon at an international level by national standards bodies.
Glossary SPAG Standards Promotion and Applications Group; based in Europe and working with COS on the development and promotion of conformance tests procedures for OSI products. TCP transmission control protocol. A network protocol that establishes and maintains connections between nodes. TCP is the transport protocol used in ARPA networks. Internet protocol (IP) addresses are used to identify systems in an ARPA network. X.400 CCITT standard for electronic message handling systems (e.g.
Index A A/P calls used in a session, 29 A/P primitives short names, 24 A_ASSOC_REQ, 37 A_ASSOC_RSP, 38, 39 A_PABORT_IND, 43 A_RELEASE_REQ, 42 A_RELEASE_RSP, 42 ACSE/Presentation before running applications, 64 calls, 23 calls not supported, 19 calls, summary, 23 functions by task, 22 limitations, 19 multi-thread program example, 64 order of primitives used, 24 primitives, summary, 24, 82 summary, 15 addressing, 50 communication endpoint, 50 AP_AGAIN, 57 AP_BIND_PADDR, 35 ap_close(), 44 close communication
Index E EINTR, 62 enable API tracing, 71, 77 encoding data, 55 endpoints binding, 35 ENV_FILE parameter, null, 34 env_file, 19 environment file, 19 environment variables getting, 19 setting, 19 error checking routines, 63 error handling in multi-threaded applications, 63 establish roles initiator, 35 responder, 35 establishing an association, 34 example multi-thread program, 66 example ROSE program, 66 examples program names, 65 ROSE, reference, 66 exchanging data, 40 F file descriptors communication endpo
Index calls used, 31 send data, 40 sending and receiving data, 40 setting environment variables limitations, 19 short names used with man, 24 signal handlers, 62, 63 sptype, 57 setting, 55 standards documents, 20 supported standards, 17 X.410, 17 synchronous mode, 56 description, 56 system maximums, 61 system support 14 character file names, 14 systems supported, 14 W What is ACSE/Presentation, 15 What is ROSE, 15 who should use this manual, 20 X X.
