HP-UX SNAplus2 MS Programmers Guide HP-UX 11i Edition 2 Manufacturing Part Number: J2744-90019 E0603 United States © Copyright 2003 © Hewlett-Packard Company, 2003. 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.
Trademark Notices ActivePerl is a registered trademark of ActiveState Tool Corporation Apple and Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. AppleShare is a registered trademark of Apple Computer, Inc. CHAMELEON is a trademark of NetManage, Inc. DIGITAL and PATHWORKS are trademarks of Digital Equipment Corporation. DiskAccess is a registered trademark of Intergraph. EXCURSION is a trademark of Digital Equipment Corporation.
SunForum is a registered trademark of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark in the United States and other countries, licensed exclusively through The Open Group. VERITAS is a registered trademark of VERITAS Software Corporation. VERITAS File System is a trademark of VERITAS Software Corporation. WinDD is a trademark of Tektronix, Inc. X Window System is a trademark of the Massachusetts Institute of Technology.
Contents 1. Introduction to Management Services Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNA Management Services Support Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNAplus2 Management Services Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Management Services Application Programming Interface . . . . . . . . . . . . . . . . . . . . .
Contents Returned Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REGISTER_MS_APPLICATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VCB Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supplied Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Returned Parameters . . . . .
Contents Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NMVT_RECEIVED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VCB Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 8
Publishing History The manual publishing date and part number indicate its current edition. The publishing date will change when a new edition is published. Minor changes may be made without changing the publishing 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.
Preface The HP-UX SNAplus2 MS Programmers Guide provides information on how to write Management Services (MS) applications to use the SNAplus2 MS application programming interface (API). More specifically, this book contains the information required to develop C-language application programs that use the MS API to communicate with remote network management applications. It also provides a brief overview of MS concepts and provides detailed reference information for experienced MS programmers.
Prerequisite Knowledge Before you read this guide, you should have a knowledge of the following subjects: 12 • Systems Network Architecture (SNA) and Advanced Peer-to-Peer Networking (APPN) concepts (see “Related Publications”) • The C compiler cc • HP-UX version 10.
About This Book This section explains how information is organized and presented in this book. Organization of This Book This book is organized as follows: Chapter 1, “Introduction to Management Services.” Provides an overview of SNAplus2 MS support. It describes the various levels of SNA network management support, the function sets and optional subsets supported by the SNAplus2 MS API, and the functions provided by the SNAplus2 MS verbs. Chapter 2, “Writing MS Applications.
Table 1 14 Typographic Conventions (Continued) Special Element Sample of Typography File or path name libmgr.sl Header file ms_c.
SNAplus2 Publications SNAplus2 publications include user guides, administrator guides, and programmer guides. The following sections describe the contents of each book. Publications for Users SNAplus2 provides the following user guides: HP-UX SNAplus2 General Information Provides an introduction to SNAplus2 and explains key product concepts and features.
Explains how to install the SNAplus2 software and set up system files. HP-UX SNAplus2 Upgrade Guide Provides information about upgrading to the current version of SNAplus2 from previous versions. It includes information about converting configuration files, rebuilding applications that use the SNAplus2 application program interfaces (APIs), and changes in other SNAplus2 functions. HP-UX SNAplus2 Administration Guide Explains how to enable, configure, and manage SNAplus2.
Contains the information you need to write application programs using Common Programming Interface for Communications (CPI-C). SNAplus2 3270 & TN3270 HLLAPI Programmers Guide Contains the information you need to write application programs using High-Level Language Application Program Interface (HLLAPI). SNAplus2 LUA Programmers Guide Contains the information you need to write applications using the Conventional LU Application Programming Interface (LUA).
Related Publications For detailed information about SNA Management Services, refer to the following IBM document: • Systems Network Architecture: Management Services Reference, SC30-3346 For general information about SNA, APPN, or LU 6.2 architecture, refer to the following IBM documents: • APPN Architecture and Product Implementations Tutorial, GG24-3669 • Systems Network Architecture: — APPN Architecture Reference, SC30-3422 — Formats, GA27-3136 — LU6.
1 Chapter 1 Introduction to Management Services 19
Introduction to Management Services Overview Overview This chapter introduces the SNAplus2 Management Services (MS) application programming interface (API). It includes information about the various types of MS support in SNA and about accessing them through SNAplus2.
Introduction to Management Services SNA Management Services Support Levels SNA Management Services Support Levels SNA defines the following levels of MS support. Each level corresponds to a different generation of products that implement this support.
Introduction to Management Services SNA Management Services Support Levels OS/2 Communications Server/2 and NetView Version 2, Release 2 (as a subarea LU rather than a CP) provide MDS-level support.
Introduction to Management Services SNAplus2 Management Services Support SNAplus2 Management Services Support The SNAplus2 MS API enables an application to communicate with other MS products or applications on the SNA network. SNAplus2 can support NMVT-level and MDS-level applications. The partner MS application can implement any of the levels described in “SNA Management Services Support Levels”. SNAplus2 performs any data conversion that is required.
Introduction to Management Services Management Services Application Programming Interface Management Services Application Programming Interface The SNAplus2 MS API comprises the following elements: MS verbs Verbs are issued by an MS application to do the following: • Inform SNAplus2 when it needs SNAplus2 resources to support receiving MS data and status indications. • Send MS data (in either NMVT format or MDS_MU format) to an MS application elsewhere in the network.
Introduction to Management Services Management Services Applications Management Services Applications The verbs and entry points you use when you write an MS application depend on whether the MS application: • Only sends data • Sends and receives data MS Applications That Only Send Data This most simple type of application only sends data and never receives any data from the SNAplus2 node.
Introduction to Management Services Management Services Applications • The REGISTER_MS_APPLICATION verb registers the application with SNAplus2 as an MDS-level application that can accept MDS_MUs. An option on the verb enables the application to request information about the focal point for a particular MS category. SNAplus2 uses the MDS_MU_RECEIVED indication, the FP_NOTIFICATION indication, or both, to pass the required data to the application.
Introduction to Management Services Management Services Applications • Receive status information from the SNAplus2 node when SNAplus2 returns the following status indications: — The FP_NOTIFICATION indication provides information about the focal point for a particular MS category. SNAplus2 returns this indication to an MDS-level application that has registered to receive focal point information.
Introduction to Management Services Management Services Applications 5. After the application ends its registration with SNAplus2, it must issue a DISCONNECT_MS_NODE verb to end communication with the SNAplus2 node and free the resources associated with the application. For more information about the synchronous and asynchronous entry points, see “Description of the MS API Entry Points”.
Introduction to Management Services NMVT Routing NMVT Routing When SNAplus2 receives an NMVT from a remote node, it uses the MS major vector key and the destination application name subfields of the NMVT to determine to which MS application to send the NMVT in the following order of preference: 1. SNAplus2 attempts to find an NMVT-level application that has registered with an application name matching the NMVT's destination name, in the following order of preference: a.
Introduction to Management Services NMVT Routing 30 Chapter 1
2 Chapter 2 Writing MS Applications 31
Writing MS Applications Overview Overview This chapter describes how an MS application: 32 • Uses the MS API entry points • Schedules asynchronous events • Is compiled and linked to use the MS API Chapter 2
Writing MS Applications Description of the MS API Entry Points Description of the MS API Entry Points An application accesses the MS API using the following entry point function calls: ms An application uses this entry point to issue an MS verb synchronously. SNAplus2 does not return control to the application until verb processing has finished. All MS verbs except REGISTER_MS_APPLICATION and REGISTER_NMVT_APPLICATION can be issued through this entry point.
Writing MS Applications Description of the MS API Entry Points All MS verbs can be issued throught this entry point. The REGISTER_MS_APPLICATION and REGISTER_NMVT_APPLICATION verbs must be issued through this entry point. An application must use this entry point if either of the following conditions is true: • The application needs to receive MS data and status indications. • The application cannot suspend while waiting for SNAplus2 to completely process a verb.
Writing MS Applications Description of the MS API Entry Points For the UNREGISTER_MS_APPLICATION, UNREGISTER_NMVT_APPLICATION, and DISCONNECT_MS_NODE verbs, the application supplies the value that was returned on the CONNECT_MS_NODE verb. This parameter is used to identify the target SNAplus2 node. For all other verbs, this parameter is not used; set it to 0 (zero). msvcb Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued.
Writing MS Applications Description of the MS API Entry Points processing at a later time. In some cases, verb processing is complete when SNAplus2 returns control to the application, so SNAplus2 does not use the application's callback routine.
Writing MS Applications Description of the MS API Entry Points Pointer to a Verb Control Block (VCB) that contains the parameters for the verb being issued. The VCB structure for each verb is described in Chapter 3, “Management Services Verbs.” These structures are defined in the MS API header file ms_c.h. comp_proc The callback routine that SNAplus2 will call when the verb completes.
Writing MS Applications Description of the MS API Entry Points SNAplus2 calls the supplied callback routine to indicate when the verb processing completes. The application can then examine the VCB parameters. Using the Asynchronous Entry Point When using the asynchronous entry point, note the following: • If an application specifies a null pointer in the comp_proc parameter, the verb will complete synchronously (as though the application issued the verb using the synchronous entry point).
Writing MS Applications Description of the MS API Entry Points void * AP_CORR ); typedef union ap_corr msvcb, corr { void * unsigned long int } AP_CORR; corr_p; corr_l; corr_i; Supplied Parameters SNAplus2 calls the callback routine with the following parameters: target_handle For MS data and status indications, SNAplus2 passes the target handle that was supplied with the REGISTER_MS_APPLICATION or REGISTER_NMVT_APPLICATION verb. For completion of verbs, this parameter is undefined.
Writing MS Applications Description of the MS API Entry Points Using the Callback Routine for Indications The callback routine supplied with the REGISTER_MS_APPLICATION VCB can receive the following indications: • FP_NOTIFICATION (if the application requested this information when registering) • MDS_MU_RECEIVED • MS_STATUS The callback routine supplied with the REGISTER_NMVT_APPLICATION VCB can receive the following indications: • NMVT_RECEIVED (if the application did not request conversion from NMVT
Writing MS Applications Description of the MS API Entry Points • If an MDS-level application uses REGISTER_NMVT_APPLICATION to receive incoming NMVTs after conversion to MDS_MUs, it must be capable of receiving a data length of 700 bytes, which allows for the maximum NMVT size together with the MDS_MU header information.
Writing MS Applications Scheduling Asynchronous Events Scheduling Asynchronous Events The method that an application uses to schedule asynchronous events depends on which of the following types of application it is: Single-threaded applications Applications that are based around a single main thread of execution to receive and process requests Multithreaded applications Applications that can have several threads of execution receiving and processing requests Motif applications Applications that use the Mot
Writing MS Applications Scheduling Asynchronous Events generate any subsequent callbacks. For more information about callbacks, see “The Callback Routine Specified on the ms_async Entry Point”. The application scheduling mode assumes that the application is structured as a main loop consisting of a call to either select or poll followed by code to process event information returned by the select or poll call.
Writing MS Applications Scheduling Asynchronous Events Asynchronous verbs are implemented by making callbacks to the application from signal catcher context. The disadvantages of signal-based scheduling mode are: • Applications that receive work from multiple sources are difficult to write • Applications are required to use HP-UX V.
Writing MS Applications Scheduling Asynchronous Events Multithreaded Applications SNAplus2 API libraries are available for linking with multithreaded applications. When you develop applications to operate in a multithreaded environment, the following restrictions apply: • When an application uses the asynchronous entry point, the application is required to maintain the consistency of its data structures when callbacks are invoked.
Writing MS Applications Scheduling Asynchronous Events The SNA_USE_XT_SCHED call has no return values. It calls the XtAppAddInput function to register the SNA work sources. When work subsequently arrives on the SNA file descriptor, the Xt library scheduling loop calls the SNA event handler, which then makes any required API callbacks to the application. NOTE 46 SNA callbacks can also be made from within other calls into the SNA library.
Writing MS Applications Compiling and Linking the MS Application Compiling and Linking the MS Application Applications are compiled with different options in order to select one of the scheduling modes described in “Scheduling Asynchronous Events”. NOTE Applications that use asynchronous API callbacks must either be built as multithreaded applications or include support for the application scheduled mode. Motif applications must include the code fragment described in “Motif Applications”.
Writing MS Applications Compiling and Linking the MS Application have been built with previous versions of SNAplus or SNAplus2 on PA-Risc systems. These libraries are on /opt/sna/lib or /opt/sna/lib/pa20_64. There are multiple copies of some libraries to support different levels of the interfaces.
3 Chapter 3 Management Services Verbs 49
Management Services Verbs Overview Overview For each MS verb, this chapter provides the following information: • Purpose and usage of the verb. • Verb Control Block (VCB) structure used by the verb. All the VCB structures are defined in the header file ms_c.h. • Supplied parameters (VCB fields supplied to the verb). For each parameter, the following information is listed: — Description — Valid values and their meanings — Additional information where necessary • Returned parameters.
Management Services Verbs CONNECT_MS_NODE CONNECT_MS_NODE This verb connects an application to a SNAplus2 node. It returns a handle that should be used on all subsequent calls to the MS entry points. An application that only sends data using either the TRANSFER_MS_DATA verb or the SEND_MDS_MU verb and does not need to receive MS data or status indications does not need to issue this verb or supply a handle to any subsequent calls to the MS entry points.
Management Services Verbs CONNECT_MS_NODE owns a direct connection to the NetView host (the node whose PU-SSCP session is used to transmit NMVTs to the NetView program). For more information about NMVT-level programs, see Chapter 1, “Introduction to Management Services.” If any of the following conditions is true, you can set this parameter to all binary zeros (you do not need to specify the node name): • SNAplus2 is running with all components on a single HP-UX computer (not on a LAN).
Management Services Verbs CONNECT_MS_NODE Returned value for use on future verbs directed to this node. Unsuccessful Execution When a verb does not execute successfully, SNAplus2 returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
Management Services Verbs CONNECT_MS_NODE The application used the synchronous entry point to issue this verb, but another synchronous verb was in progress for this target handle. Only one synchronous verb can be in progress on a particular target handle at any time. AP_SYNC_NOT_ALLOWED The application used the synchronous MS entry point to issue this verb within a callback routine. The application must use the asynchronous entry point to issue any verb from a callback routine.
Management Services Verbs CONNECT_MS_NODE The return code from the operating system call. For the meaning of this return code, check the returned value in the file /usr/errno.h.
Management Services Verbs DISCONNECT_MS_NODE DISCONNECT_MS_NODE This verb disconnects an application from a node, freeing all resources associated with that connection. The node from which the application wants to disconnect is identified by the target_handle parameter on the call.
Management Services Verbs DISCONNECT_MS_NODE SNAplus2 does not return a secondary_rc when the verb executes successfully. Unsuccessful Execution When a verb does not execute successfully, SNAplus2 returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
Management Services Verbs DISCONNECT_MS_NODE one synchronous verb can be in progress on a particular target handle at any time. AP_VERB_IN_PROGRESS The application issued DISCONNECT_MS_NODE while a previous asynchronous MS verb was still outstanding. AP_SYNC_NOT_ALLOWED The application used the synchronous MS entry point to issue this verb within a callback routine. The application must use the asynchronous entry point to issue any verb from a callback routine.
Management Services Verbs REGISTER_MS_APPLICATION REGISTER_MS_APPLICATION The REGISTER_MS_APPLICATION verb registers the MS application with SNAplus2 as an MDS-level application that can receive MDS_MUs. Before issuing this verb, the application must issue CONNECT_MS_NODE to obtain a target handle for the SNAplus2 node. This handle is a required parameter to the MS entry point for REGISTER_MS_APPLICATION.
Management Services Verbs REGISTER_MS_APPLICATION A name identifying this application. An application can register more than once using different application names. The name has the following requirements: • It cannot match the name used by any other application that is currently registered as an MS application. • It cannot be either NODE or UNIX, which are reserved for use by SNAplus2 components. • It must be eight characters long; pad on the right with EBCDIC space characters (0x40) if necessary.
Management Services Verbs REGISTER_MS_APPLICATION SNAplus2 returns details of the focal point using an FP_NOTIFICATION indication on the callback routine that was supplied with REGISTER_MS_APPLICATION. If the focal point subsequently changes, SNAplus2 sends another FP_NOTIFICATION with the new information. max_rcv_size The maximum number of bytes that the application can accept in one message.
Management Services Verbs REGISTER_MS_APPLICATION One of the following: AP_MS_APPL_NAME_ALREADY_REGD Another application is currently registered with the specified name, or the application specified one of the two reserved names, NODE and UNIX. AP_INVALID_APPLICATION_NAME The supplied application name contains a character not in the EBCDIC type-1134 character set, and the name is not one of the MS Discipline-Specific Application Program names.
Management Services Verbs REGISTER_MS_APPLICATION AP_STATE_CHECK secondary_rc AP_INVALID_TARGET_STATE The application issued this verb while CONNECT_MS_NODE or DISCONNECT_MS_NODE was outstanding. SNAplus2 Software Not Active If the verb does not execute because the SNAplus2 software is not active, SNAplus2 returns the following parameter: primary_rc One of the following: AP_COMM_SUBSYSTEM_NOT_LOADED The SNAplus2 software is not loaded. AP_COMM_SUBSYSTEM_ABENDED The SNAplus2 software has failed.
Management Services Verbs REGISTER_MS_APPLICATION An operating system call failed during processing of the verb. secondary_rc 64 The return code from the operating system call. For the meaning of this return code, check the returned value in the file /usr/errno.h.
Management Services Verbs REGISTER_NMVT_APPLICATION REGISTER_NMVT_APPLICATION The REGISTER_NMVT_APPLICATION verb registers the MS application with SNAplus2 as an NMVT-level application that can receive NMVTs. This verb is normally used by an NMVT-level application, but it can also be used by an MDS-level application that can receive NMVTs after they have been converted to MDS_MUs. Before issuing this verb, the application must issue CONNECT_MS_NODE to obtain a target handle for the SNAplus2 node.
Management Services Verbs REGISTER_NMVT_APPLICATION opcode AP_REGISTER_NMVT_APPLICATION ms_appl_name A name identifying this application. An application can register more than once using different application names. This name has the following requirements: • It cannot match the name used by any other application that is currently registered to accept the same range of keys as specified by the ms_vector_key_type parameter.
Management Services Verbs REGISTER_NMVT_APPLICATION The 2-byte hexadecimal value of a particular major vector key. AP_SPCF_KEYS Accept all major vector keys in the range 0x8061–0x8064. This value is intended for use by an application that is implementing the SNA Service Point Command Facility (SPCF) function; do not use it if your application is not implementing this function. The ms_appl_name parameter must not match the application name of any other application that is registered to accept SPCF keys.
Management Services Verbs REGISTER_NMVT_APPLICATION Specifies whether the registering application is MDS-level and requires conversion of NMVTs to MDS_MUs. Specify one of the following: AP_YES The application is MDS-level; NMVTs should be converted to MDS_MUs. AP_NO The application is NMVT-level; NMVTs should not be converted.
Management Services Verbs REGISTER_NMVT_APPLICATION AP_ALL_APPL_ALREADY_REGISTERED Indicates one of the following error conditions: • This application has already registered to accept all keys. • Another application has registered to accept all keys using the same application name. • The application registered to accept all keys using one of the two reserved names, NODE and UNIX.
Management Services Verbs REGISTER_NMVT_APPLICATION AP_SPCF_APPL_ALREADY_REGD Indicates one of the following error conditions: • This application has already registered to accept SPCF keys. • Another application has registered to accept SPCF keys using the same application name. • The application registered to accept SPCF keys using one of the two reserved names NODE and UNIX. AP_SYNC_NOT_ALLOWED The application used the synchronous MS entry point to issue this verb within a callback routine.
Management Services Verbs REGISTER_NMVT_APPLICATION AP_COMM_SUBSYSTEM_NOT_LOADED The SNAplus2 software is not loaded. AP_COMM_SUBSYSTEM_ABENDED The SNAplus2 software has failed. SNAplus2 does not return a secondary_rc when the SNAplus2 software is not active. System Error If the verb does not execute because of a system error, SNAplus2 returns the following parameters: primary_rc AP_UNEXPECTED_SYSTEM_ERROR An operating system call failed during processing of the verb.
Management Services Verbs SEND_MDS_MU SEND_MDS_MU An MDS-level application uses this verb to send network management data in MDS_MU format. An MDS-level application can also send data in NMVT format using TRANSFER_MS_DATA. To send alert information, always use TRANSFER_MS_DATA. Do not use SEND_MDS_MU to send alert information. The application can supply a complete MDS_MU to be sent, or it can supply some of the required subvectors and request SNAplus2 to add additional subvectors.
Management Services Verbs SEND_MDS_MU unsigned char } SEND_MDS_MU; *dptr; /* Data */ Supplied Parameters An application supplies the following parameters when it issues SEND_MDS_MU: opcode AP_SEND_MDS_MU options This parameter is a one-byte value, with individual bits used as follows to indicate the options selected. Bit 0 is the most significant and bit 7 is the least significant bit.
Management Services Verbs SEND_MDS_MU contains a Product Set ID subvector, SNAplus2 adds its own Product Set ID subvector immediately preceding the existing one. 1 Requests that SNAplus2 not add the subvector. Bit 2 Reserved. Must be set to 0. Bit 3 Log the data in the SNAplus2 error log file. Set this bit to one of the following: 0 Requests that SNAplus2 log the data. 1 Requests that SNAplus2 not log the data.
Management Services Verbs SEND_MDS_MU N indication that describes the destination application and has the fp_routing parameter set to AP_DIRECT. For more information, see “FP_NOTIFICATIO N”. 1 Requests that SNAplus2 use direct routing. Bits 5-7 Reserved. Must be set to 0. originator_id Name of the component that issued the verb. If the data is being logged in the SNAplus2 error log file, this name is used to identify the originator of the log message; otherwise, it is not used.
Management Services Verbs SEND_MDS_MU NMVTs should specify the pu_name received in the MDS_MU_RECEIVED indication. In this case, the pu_name must match a pu_name specified on the definition of a link station (LS); the MDS_MU is sent over this link station. For more information about defining an LS, refer to the SNAplus2 Administration Guide. All binary zeros Use this value for MDS_MUs that are to be transported using the normal MDS routing protocols.
Management Services Verbs SEND_MDS_MU primary_rc AP_OK SNAplus2 does not return a secondary_rc when the verb executes successfully. Unsuccessful Execution When a verb does not execute successfully, SNAplus2 returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.
Management Services Verbs SEND_MDS_MU AP_SSCP_PU_SESSION_NOT_ACTIVE The application specified a PU name, but no session exists between this PU and an SSCP. AP_SYNC_PENDING This verb was issued using the synchronous entry point, but another synchronous verb was in progress for this target handle. Only one synchronous verb can be in progress on a particular target handle at any time. AP_SYNC_NOT_ALLOWED The application used the synchronous MS entry point to issue this verb within a callback routine.
Management Services Verbs SEND_MDS_MU The SNAplus2 local node is not configured to support MDS-level network management applications. Only NMVT-level applications can be used. SNAplus2 does not return a secondary_rc when it is not configured for MDS-LEVEL support. System Error If the verb does not execute because of a system error, SNAplus2 returns the following parameters: primary_rc AP_UNEXPECTED_SYSTEM_ERROR An operating system call failed during processing of the verb.
Management Services Verbs TRANSFER_MS_DATA TRANSFER_MS_DATA This verb is used by: • NMVT-level applications to respond to previously received NMVT requests and to send unsolicited NMVTs • NMVT-level and MDS-level applications to send unsolicited NMVTs (such as alert information) The application can supply a complete NMVT to be sent, or it can supply some of the required subvectors and request SNAplus2 to add header information or additional subvectors.
Management Services Verbs TRANSFER_MS_DATA Supplied Parameters The application supplies the following parameters when it issues the TRANSFER_MS_DATA verb: opcode SV_TRANSFER_MS_DATA data_type Specify one of the following values: SV_NMVT The data contains a complete NMVT. SNAplus2 converts the data to MDS_MU or CP_MSU format if the data contains an alert and the alert is to be sent to an MDS-level or migration-level focal point.
Management Services Verbs TRANSFER_MS_DATA The data contains problem determination statistics. SNAplus2 always logs the data but does not send it to any focal point. options A one-byte value, with individual bits indicating the options selected. Bit 0 is the most significant and bit 7 is the least significant bit. For compatibility with other implementations, the bit values for bits 0–3 are defined so that a value of 1 indicates no action and a value of 0 indicates an action.
Management Services Verbs TRANSFER_MS_DATA immediately preceding the existing one. 1 Requests that SNAplus2 not add the subvector. Bit 2 Send the data to the focal point or the PU specified by the pu_name parameter if this verb is being used to send a reply to a previously received NMVT. Set this bit to one of the following: 0 Requests that SNAplus2 send the data 1 Requests that SNAplus2 not send the data Bit 3 Log the data in the SNAplus2 error log file.
Management Services Verbs TRANSFER_MS_DATA This optional parameter is an ASCII string of up to eight characters, using any locally displayable characters. Set the first character to 0x00 if you do not want to include it. pu_name Destination physical unit for this NMVT. Set this to one of the following: A name of a PU Specify an 8-byte type-A EBCDIC string, padded to the right with EBCDIC spaces (0x40).
Management Services Verbs TRANSFER_MS_DATA dlen Length of the data supplied by the application. The maximum length of an NMVT is 512 bytes. If the application is supplying a complete NMVT, the data length must not exceed 512 bytes. If the application is supplying alert subvectors, or requesting SNAplus2 to add one or more subvectors to the supplied data, the total length after addition of any required headers and subvectors must not exceed 512 bytes.
Management Services Verbs TRANSFER_MS_DATA SV_PARAMETER_CHECK secondary_rc One of the following: SV_INVALID_DATA_TYPE The supplied data_type parameter is not one of the valid values. AP_INVALID_DATA_SIZE One of the following occurred: • The application supplied a data string longer than the maximum NMVT size of 512 bytes.
Management Services Verbs TRANSFER_MS_DATA synchronous verb can be in progress on a particular target handle at any time. SV_SSCP_PU_SESSION_NOT_ACTIVE The application requested SNAplus2 to send data by setting bit 2 of the options parameter to 0, but the session to the appropriate PU was not active. AP_SYNC_NOT_ALLOWED The application used the synchronous MS entry point to issue this verb within a callback routine.
Management Services Verbs UNREGISTER_MS_APPLICATION UNREGISTER_MS_APPLICATION The UNREGISTER_MS_APPLICATION verb indicates to SNAplus2 that this application, which previously registered to receive MDS_MUs, no longer wants to receive them. After this verb completes successfully, SNAplus2 no longer sends any received MDS_MUs to the application. Before terminating, an application should always issue UNREGISTER_MS_APPLICATION for all its registered application names, followed by DISCONNECT_MS_NODE.
Management Services Verbs UNREGISTER_MS_APPLICATION Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful. Successful Execution If the verb executes successfully, SNAplus2 returns the following parameter: primary_rc AP_OK SNAplus2 does not return a secondary_rc when the verb executes successfully.
Management Services Verbs UNREGISTER_MS_APPLICATION State Check If the verb fails to execute because of a state error, SNAplus2 returns the following parameters: primary_rc AP_STATE_CHECK secondary_rc One of the following: AP_INVALID_TARGET_STATE The application issued this verb while CONNECT_MS_NODE or DISCONNECT_MS_NODE was outstanding. AP_SYNC_PENDING This verb was issued using the synchronous entry point, but another synchronous verb was in progress for this target handle.
Management Services Verbs UNREGISTER_MS_APPLICATION MDS Support Not Configured If the verb does not execute because the SNAplus2 configuration does not allow it, SNAplus2 returns the following parameter: primary_rc AP_FUNCTION_NOT_SUPPORTED The SNAplus2 local node is not configured to support MDS-level network management applications. Only NMVT-level applications can be used. SNAplus2 does not return a secondary_rc when it is not configured for MDS-LEVEL support.
Management Services Verbs UNREGISTER_NMVT_APPLICATION UNREGISTER_NMVT_APPLICATION The UNREGISTER_NMVT_APPLICATION verb indicates to SNAplus2 that this application, which previously registered to receive NMVTs for a given application name, no longer wants to receive them for that name. If the application used the same application name in multiple REGISTER_NMVT_APPLICATION verbs to accept different types of NMVTs, unregistering this name means that the application no longer receives any of these NMVTs.
Management Services Verbs UNREGISTER_NMVT_APPLICATION REGISTER_NMVT_APPLICATION. The string must be eight characters long; pad on the right with EBCDIC space characters (0x40) if necessary. Returned Parameters After the verb executes, SNAplus2 returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful.
Management Services Verbs UNREGISTER_NMVT_APPLICATION State Check If the verb fails to execute because of a state error, SNAplus2 returns the following parameters: primary_rc AP_STATE_CHECK secondary_rc One of the following: AP_INVALID_TARGET_STATE The application issued this verb while CONNECT_MS_NODE or DISCONNECT_MS_NODE was outstanding. AP_SYNC_PENDING This verb was issued using the synchronous entry point, but another synchronous verb was in progress for this target handle.
Management Services Verbs UNREGISTER_NMVT_APPLICATION System Error If the verb does not execute because of a system error, SNAplus2 returns the following parameters: primary_rc AP_UNEXPECTED_SYSTEM_ERROR An operating system call failed during processing of the verb. secondary_rc The return code from the operating system call. For the meaning of this return code, check the returned value in the file /usr/errno.h.
Management Services Verbs UNREGISTER_NMVT_APPLICATION 96 Chapter 3
4 Chapter 4 Management Services Indications 97
Management Services Indications Overview Overview For each indication, this chapter provides the following information: • Purpose of the indication, and the conditions in which SNAplus2 returns it to an application. • Description of the indication. For consistency, the term verb control block (VCB) is used to describe the indications, although this structure is not associated with a verb issued by the application. All the VCB structures are defined in the header file ms_c.h.
Management Services Indications FP_NOTIFICATION FP_NOTIFICATION SNAplus2 sends this status indication to an MDS-level application that has requested information about the focal point for a particular MS category. The application requests this information by issuing REGISTER_MS_APPLICATION with the name of a particular MS category specified as part of the focal point data string. SNAplus2 sends FP_NOTIFICATION to inform the application of its current focal point for that category.
Management Services Indications FP_NOTIFICATION Specifies whether applications should use default or direct routing when sending MDS_MUs to this focal point. Possible values are: AP_DEFAULT MDS_MUs should be delivered to the focal point using default routing. AP_DIRECT MDS_MUs should be routed on a session directly to the focal point. fp_data_length Length of focal point data. This can be up to 78 bytes.
Management Services Indications MDS_MU_RECEIVED MDS_MU_RECEIVED SNAplus2 uses this data indication to route an MDS_MU to an MDS-level application in the following cases: • A remote MDS-level application has sent an MDS_MU, and this application has used REGISTER_MS_APPLICATION to accept MDS_MUs. • A remote application has sent an NMVT, and this application has used REGISTER_NMVT_APPLICATION to accept NMVTs after conversion to MDS_MUs.
Management Services Indications MDS_MU_RECEIVED opcode AP_MDS_MU_RECEIVED first_message Indicates whether this message is the first, or only, message for this MDS_MU. The MDS_MU is normally sent to the application as a single message (both first_message and last_message are AP_YES). However, if the MDS_MU is larger than the max_rcv_size specified when the application issued REGISTER_MS_APPLICATION, SNAplus2 segments the MDS_MU and sends it to the application as multiple messages.
Management Services Indications MDS_MU_RECEIVED pu_name If the MDS_MU was converted from an incoming NMVT, this parameter is the name of the physical unit from which the NMVT was received. If the NMVT requires a response, the application must send the response using the SEND_MDS_MU verb, and must set the pu_name parameter of the SEND_MDS_MU to this name.
Management Services Indications MS_STATUS MS_STATUS SNAplus2 sends this status indication to a registered application (either MDS-level or NMVT-level) to inform the application of one of the following changes in the status of the SNAplus2 system: • The application's communications path to the SNAplus2 local node has been lost because the connected node or an associated component is no longer active. • The SNAplus2 software has been stopped.
Management Services Indications MS_STATUS AP_MS_STATUS status AP_TARGET_HAS_DIED This value indicates that the connected node or the SNAplus2 software is no longer running. dead_target_handle A null value for this parameter indicates that the SNAplus2 software on the local computer (where the application is running) has been stopped. All target handles that the application was using are disconnected and are no longer valid.
Management Services Indications NMVT_RECEIVED NMVT_RECEIVED SNAplus2 uses this data indication to route an NMVT received from a remote node to an NMVT-level application that has registered to receive NMVTs. For information about how SNAplus2 determines which MS application receives an incoming NMVT, see “NMVT Routing”. This indication is returned using the callback routine that the application supplied on the REGISTER_NMVT_APPLICATION verb.
Management Services Indications NMVT_RECEIVED If the incoming NMVT requires a response, the application must send the response using TRANSFER_MS_DATA and must set the pu_name parameter of TRANSFER_MS_DATA to the pu_name returned here. nmvt_length Length of NMVT data, which can be up to 512 bytes. nmvt Full NMVT, containing MS major vector of the type or types specified on the REGISTER_NMVT_APPLICATION.
Management Services Indications NMVT_RECEIVED 108 Chapter 4
A Appendix A MS Function Sets 109
MS Function Sets Overview Overview This appendix provides information about the SNA MS function sets that the SNAplus2 MS API supports. For more information about these function sets, refer to the IBM manual Systems Network Architecture: APPN Architecture Reference.
MS Function Sets Base Function Sets Base Function Sets The SNAplus2 MS API supports the following base function sets: • Management Services—Multiple-Domain Support (MDS) 150 SNA/MS MDS Common Base 151 SNA/MS MDS End Node Support • Management Services—MS Capabilities Function Set 160 SNA/MS MS_CAPS Base End Node Support 161 SNA/MS MS_CAPS Have a Backup or Implicit Focal Point • Management Services—Entry Point Alert Function Set 170 SNA/MS MS EP Alert Base Subset Appendix A 111
MS Function Sets Optional Function Sets Optional Function Sets The SNAplus2 MS API supports the following optional function sets: • Management Services—MS Capabilities Function Set 162 SNA/MS MS_CAPS Be a Sphere of Control (SOC) End Node • Management Services—Entry Point Alert Function Set 171 SNA/MS Problem Diagnosis Data in Alert 174 SNA/MS Operator Initiated Alert 175 SNA/MS Qualified Message Data in Alert 176 SNA/MS Self-Defining Message Text Subvector in Alert 177 SNA/MS LAN Alert 178 SNA/MS SDLC/L
MS Function Sets Function Sets Not Supported Function Sets Not Supported SNAplus2 MS does not provide support for the following function sets: Appendix A • Management Services—File Services (option sets 1500, 1501). • Management Services—Change Management (option sets 1510–1518). • Management Services—Operations Management (option sets 1520, 1521). Option set 1520, SNA/MS Common Operations Services, is implemented by the SNAplus2 Service Point Command Facility.
MS Function Sets Function Sets Not Supported 114 Appendix A
Index A application scheduled mode, 42 asynchronous entry pointSee ms_async entry point, 33 C callback routine comp_proc parameter, 37 overview, 38 requirements, 40 supplied to REGISTER_* verbs, 40 child process, 41 communications with the node ending, 56 failure, 104 starting, 51 comp_proc (callback routine), 37 CONNECT_MS_NODE overview, 51 returned parameters, 52 supplied parameters, 51 VCB structure, 51 corr (correlator), 37, 39 CP_MSU, 21 D data structure MDS_MU, 101 NMVT, 106 DISCONNECT_MS_NODE overvie
Index multithreaded applications, 45 N NMVT conversion to MDS_MU, 29, 101 destination name, 29 major vector key, 29 received data indication, 106 routing, 29 NMVT_RECEIVED description, 106 how used, 27 parameters, 106 VCB structure, 106 NMVT-level products, 21 node, communications with ending, 56 failure, 104 starting, 51 P prerequisite knowledge, 12 R received data indication MDS_MU, 101 NMVT, 106 received data indications, 24, 98 receiving MS data, 26 REGISTER_MS_APPLICATION description, 59 returned param
Index NMVT-level application, 92 V VCB structure, pointer to, 35, 37, 39 VCB structures, defined in header file, 50 verb summary, 24 verbs, reference information, 50 117
