home *** CD-ROM | disk | FTP | other *** search
═══ 1. Introduction ═══ To manage your network remotely, you can initiate commands from the NetView program that are processed on a workstation that runs Operating System/2* (OS/2*). The standard output generated by a command is returned to the NetView program. Note: Throughout this book, use of the phrase the NetView program refers to the host NetView program, not to the NetView/PC program. There are two components that provide for this network management capability. These two components are Service Point Application Router (SPA Router) and Remote Operations Service (ROP Service). SPA Router and ROP Service provide the following features: o Support of multiple local area networks (LANs) and multiple physical units (PUs) o Administration of large area networks o A tool for system administration o Administration of different domains SPA Router is an OS/2 program that receives the command from the NetView program and sends it to the specified application. The application can be any OS/2-based product that runs in protected mode. The advantage of having a separate program, SPA Router, that directs the commands to the applications is that multiple OS/2 applications can receive commands concurrently. ROP Service is an application that processes (on the OS/2 workstation) the commands sent by the NetView program through SPA Router. The commands sent to ROP Service may be any OS/2 commands that have a command line interface and that do not need interactive user input. In addition to using ROP Service, you can also send commands from the NetView program through SPA Router to IBM* LAN Network Manager Version 1.0 or 1.1, and you can use the application programming interface (API) for SPA Router to develop your own applications. Related Topics: Using the SPA Router and ROP Service Structure of the SPA Router and ROP Service Configurations Supported by the SPA Router and ROP Service Issuing OS/2 Commands Using NetView RUNCMDs Operating the NetView Program ═══ 1.1. Using SPA Router and ROP Service ═══ The two components, SPA Router and ROP Service, can be run and managed together or separately. One way you might use the components is to run SPA Router and ROP Service to provide remote operations capability from the NetView program. In addition, you can simultaneously run applications that use the SPA Router API, such as IBM LAN Network Manager Version 1.0 or 1.1. ═══ <hidden> Structure of the SPA Router and ROP Service ═══ This figure illustrates the structure of using the SPA Router and ROP Service. ═══ <hidden> Configurations Supported by the SPA Router and ROP Service ═══ The diagram at the bottom of this screen illustrates three of the configurations supported by SPA Router and ROP Service. Configuration 1 shows a Personal System/55* (PS/55*) workstation that is a local area network (LAN) server acting as a gateway between the NetView* program and the LAN. The PS/55 server is a physical unit (PU) that is connected to the host by Systems Network Architecture (SNA). The PS/55 server is also running SPA Router and ROP Service and thus is a service point. In this configuration, any OS/2 command can be issued to the server acting as a gateway. Similarly, the other servers on the LAN can be sent the same OS/2 commands by issuing NET ADMIN commands to the gateway server. The gateway server then distributes the NET ADMIN command to the intended server on the LAN for execution by that server. Configuration 2 shows a PS/55 workstation connected as a PU to the host by SNA. The PS/55 workstation is running SPA Router and ROP Service. This configuration illustrates the ability to issue commands from the NetView program to any workstation connected as a PU and running appropriate service point software. This configuration might be appropriate for an environment where there are single-user workstations that are not on a LAN. Configuration 3 is exactly like the first configuration except the PS/55 PU that is connected to the host is running LAN Requester instead of LAN Server. This configuration illustrates that the PS/55 gateway acting as a service point only needs to run LAN Requester (rather than LAN Server) to distribute on the LAN the commands received from the NetView program through SPA Router and ROP Service. These three configurations need not be distinct. That is, an environment can contain one, two, or all three types of configurations. The SPA Router and ROP Service rely on the program being invoked in the service point to provide the transport mechanism needed in passing the command from the service point to the workstation or the intended entity in the network. In the case of IBM LAN Server and LAN Requester, the NET command provides this transport in a LAN environment. Other network management applications may provide their command transport mechanism based on LU 6.2, X.25, IEEE data link control (DLC), NetBIOS, or a higher level interface, such as named pipe. The ROP Service extended service point provides the ROP Service function for workstations that are not defined as a service point (SP) or do not have peer-to-peer communication capability. The target workstation is defined in the RUNCMD that is sent to the ROP Service. Then a NetBIOS connection is made between the ROP Service workstation and the ROP Service extended service point workstation. The NetBIOS name for each workstation is derived from the FFST/2 workstation ID (WSID). The service point and the ROPS extended service point workstations must have unique WSIDs. These names can be set by doing the following: 1. Select the FFST/2 folder 2. Select Message Console 3. Select Hardware Information from the Options menu 4. Type the WSID in the Workstation ID field Configurations 1 and 3 show examples of how ROP Service extended service point can be configured. This figure illustrates the configurations supported by SPA Router and ROP Service. ═══ 1.2. Issuing OS/2 Commands Using NetView RUNCMDs ═══ You use the Command Facility of the NetView program to issue commands through SPA Router to ROP Service. Specifically, you issue RUNCMD commands (RUNCMDs). These commands use the following syntax: >>──RUNCMD──SP=service point PU,───APPL=application name,──OP=Operator ID999───────────────────────> >──┬──────────────────┬──┬───────────────┬──┬────────────────────────┬──OS/2 command──────────────>< └─PASS=password999─┘ └─RCO=option999─┘ └─WSID=workstation ID999─┘ Note: The operator ID, password, option, workstation ID, and OS/2 command variables are used for ROP Service only. Warning: When you issue a RUNCMD, all the information, including operator ID and password, is sent in the command. This command is not secured in any way. The command is displayed on the screen and entered into the NetView log. If passwords are sent to ROP Service, you must secure the terminal and the NetView log to ensure data is not accessed by unauthorized personnel. Examples Related Topic: Using REXX Executable Files and Command Lists ═══ <hidden> service point PU ═══ The physical unit (PU) of the service point to which the command is being sent. ═══ <hidden> application name ═══ The name of the application to which the command is being sent. Note: The application name for ROP Service is REMOTEOP. ═══ <hidden> operator ID ═══ The operator ID of the NetView account issuing the command. ═══ <hidden> password ═══ The User Profile Management (UPM) password (on the OS/2 workstation) for the operator ID. The password (PASS=password;) is optional. If passwords are not used or are not checked for validity, then you do not specify PASS=password;. ═══ <hidden> option ═══ Indicates the format of the response returned to the NetView program for the command being issued. If option is YES, ROP Service returns only the return code. If option is NO, ROP Service returns the response to the command. Note: This option overrides the existing ROP Service configuration; however, this option affects only the command currently being issued. If this option is not specified, then the ROP Service configuration is used. ═══ <hidden> workstation ID ═══ The workstation identifier (WSID) of the ROPS extended service point node to which the command is being sent. If the WSID matches the ID associated with the service point machine or if the WSID is not present in the RUNCMD, the command will be executed on the service point machine. ═══ <hidden> OS/2 command ═══ The OS/2 command being issued. Any OS/2 command can be issued through the NetView program, including any of the SPA Router (RTR) commands and ROP Service (ROP) commands, which are described later in this book. ═══ <hidden> Examples ═══ The following command sends the OS/2 command DIR C: to the service point with a PU of THX350 to ROP Service, which has an application name of REMOTEOP. The operator ID of the NetView account issuing the command is TED1 and a password of D3X45Y has been set up in UPM for that operator ID. RUNCMD SP=THX350,APPL=REMOTEOP,OP=TED1;PASS=D3X45Y;DIR C: Using the same example, if there were no UPM password set up for the TED1 operator ID, then the command would be issued as follows: RUNCMD SP=THX350,APPL=REMOTEOP,OP=TED1;DIR C: The following example issues a command to an extended service point workstation with a WSID of WS001066, which is on a LAN with a service point with a PU of THX350: RUNCMD SP=THX350,APPL=REMOTEOP,OP=TED1;WSID=WS001066;START /I /C CM ═══ <hidden> Using REXX Executable Files and Command Lists ═══ You can use REXX executable files (execs) and command lists (CLISTs) to automate the process of issuing RUNCMDs. Developing REXX Executable Files and CLISTs provides examples of REXX execs and a CLIST that you might find useful when developing your own REXX execs and CLISTs. ═══ 1.3. Operating the NetView Program ═══ With the exception of using the format previously described, you operate the NetView program for use with SPA Router and ROP Service the same way you operate the NetView program with other applications. This book does not document the operation of the NetView program. For information about operating the NetView program, refer to the NetView publications listed in the Information and Planning Guide and the Overview (online). ═══ 2. Getting Started ═══ This section provides prerequisite information and steps for running SPA Router and ROP Service. Refer to Workstation Installation and Configuration Guide for information about installing SPA Router and ROP Service. Related Topics: Requirements Setting the Value for Maximum I-Field Size Using the SPA Router or ROP Service on a LAN with IBM Remote Bridges Running IBM LAN Network Manager Version 1.0 or 1.1 SPA Router and ROP Service Files Steps for Running the SPA Router and ROP Service with IBM LAN Network Manager Version 1.0 or 1.1 ═══ 2.1. Requirements ═══ The following sections describe requirements you should be aware of before installing SPA Router and ROP Service. Software Requirements The SPA Router and ROP Service, together with the command language interface (CLI), require the following software: o NetView Version 1.3 or later on the host o IBM Communications Manager Version 1.1 on the OS/2 workstation Note: For double-byte character set (DBCS) systems, the software requirement also includes the NetView DBCS feature. Memory and Disk Space Requirements SPA Router and ROP Service together require approximately 650KB of disk space. Additional disk space is required for temporary files, logs, trace files, validation table additions, and configuration file growth. Generally, allow a minimum of 500KB, and reserve about 50KB of additional space for the functions that will be necessary to operate ROP Service, such as large temporary file generation. The log file size can be configured from ROP Service. The trace file size can be adjusted from Communications Manager. The preceding requirements are the disk space for the storage of ROP Service executable files and working data only. The virtual storage required to perform ROP Service processes is dependent on the following: o The number of applications that are registered to the router o The number of commands registered to the applications like ROP Service o The requirements of the applications, such as the creation and deletion of temporary files for holding responses to be transmitted to NetView o The memory model, segmented or paged, that ROP Service is operating under o The amount of memory that is available for ROP Service functions before the system becomes overcommitted o The performance goals desired You must establish the working set for the heaviest use of ROP Service in an actual environment and provide memory and disk space to achieve the performance goals. Configuring NetBIOS for ROP Service Extended Service Point To use the ROP Service extended service point, an adapter must have NetBIOS resources configured and available. You must configure the adapter at both the service point workstation and at the workstation running the ROP Service extended service point. ═══ <hidden> Setting the Value for Maximum I-Field Size ═══ The Maximum I-field size parameter in Communications Manager is the maximum number of information field (I-field) bytes contained in the data buffer that is used by the SNA sessions for this data link control (DLC) link. For ROP Service, the maximum I-field size supported for this link must be defined as 512 bytes or greater. To make sure the maximum I-field size is at least 512 bytes, check the value for the maximum I-field size defined in the DLC Adapter Parameters window of the DLC profile. For specific steps to change your configuration, refer to information about the DLC profile in Workstation Installation and Configuration Guide. ═══ <hidden> Using SPA Router or ROP Service on a LAN with IBM Remote Bridges ═══ Note: If you will be using SPA Router or ROP Service on a LAN, discuss the following information with your network administrator or system administrator. When using SPA Router or ROP Service on a LAN for which communication must cross one or more IBM remote bridges, the maximum frame size for any of the bridges cannot be 516 bytes. If the maximum frame size were 516 bytes, then for network management vector transports (NMVTs) of greater than 516 bytes, the frame would be discarded. To ensure that the maximum frame size for a bridge is not 516 bytes, do one of the following: o If the Maximum frame size parameter is set to 0, set the line data rate to 38.4 Kbps or greater. o Set the Maximum frame size parameter to 2 (1500 bytes) or 3 (2052 bytes). Even if the maximum I-field size for Communications Manager is set to 516 or less, the maximum frame size cannot be 516. This is because 24 bytes of header are added to the NMVT; if the maximum RU size were 512 (the lowest allowed value for SPA Router and ROP Service), the addition of the 24-byte header would cause the frame to exceed a maximum frame size of 516 (512 + 24 = 536). ═══ <hidden> Running IBM LAN Network Manager Version 1.0 or 1.1 ═══ If you plan to run IBM LAN Network Manager Version 1.0 or 1.1 and SPA Router and ROP Service on the same machine, refer to Steps for Running SPA Router and ROP Service with IBM LAN Network Manager Version 1.0 or 1.1 for installation information. ═══ 2.2. SPA Router and ROP Service Files ═══ The following table lists the files copied to the \CMLIB directory by the installation process. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SPA Router, ROP Service, and ROP Extended Service Point Files │ ├────────────────────────┬─────────────────────────────────────────────────────────────────────────┤ │ FILE NAME │ DESCRIPTION │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RCKRNL.EXE │ ROP Service background process kernel executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROP.EXE │ ROP Service command line executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPPM.EXE │ ROP Service Presentation Manager executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPROUT.EXE │ SPA Router background process executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTR.EXE │ SPA Router anchor file for all command processing │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTRPM.EXE │ SPA Router Presentation Manager user interface │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROP.MSG │ SPA Router, ROP Service, and extended service point message file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPH.MSG │ SPA Router, ROP Service command-line, and extended service point │ │ │ message help file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPPM.HLP │ ROP Service Presentation Manager help file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTRPM.HLP │ SPA Router Presentation Manager help file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROP.ICO │ Icon for ROP.EXE │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTR.ICO │ Presentation Manager icon for RTR.EXE │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CMDTBL.ROP │ ROP Service command validation table │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RCKESP.EXE │ ROP Service extended service point executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPSESP.EXE │ ROP Service extended service point command line executable file │ └────────────────────────┴─────────────────────────────────────────────────────────────────────────┘ The following table lists the files copied to the \CMLIB\DLL directory by the installation process. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SPA Router and ROP Service DLL Files │ ├────────────────────────┬─────────────────────────────────────────────────────────────────────────┤ │ FILE NAME │ DESCRIPTION │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ DCJVC00.DLL │ SPA Router API DLL │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPAPI.DLL │ ROP Service API DLL │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPRES.DLL │ Resource DLL for Presentation Manager user interface │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTRDBCS.DLL │ SPA Router DBCS-related support DLL │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTRRES.DLL │ Presentation Manager resource DLL for SPA Router Presentation Manager │ │ │ user interface │ └────────────────────────┴─────────────────────────────────────────────────────────────────────────┘ The following table lists the files available on the Communications Manager/2 API Support Diskette. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SPA Router and ROP Service Sample Files │ ├────────────────────────┬─────────────────────────────────────────────────────────────────────────┤ │ ROPAPI.LIB │ ROP Service API import library │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ DCJVAPI.LIB │ SPA Router API import library │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTRAPI.LIB │ SPA Router API import library │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ RTRC.H │ Header file to access SPA Router API by C language users │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ROPAPI.H │ Header file to access ROP Service API │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ SMPECHO.C │ File containing sample program that illustrates use of some SPCF func- │ │ │ tion calls │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ SMPSPCF.C │ File containing sample program that illustrates use of all SPCF func- │ │ │ tion calls │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ SMPUTILS.C │ Utility routines needed for SMPSPCF.C sample program │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ SPCF32.MAK │ File that compiles and makes the 32-bit version of the sample program │ │ │ SMPSPCF.C │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ SPCF16.MAK │ File that compiles and makes the 16-bit version of the sample program │ │ │ SMPSPCF.C │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ECHO32.MAK │ File that compiles and makes the 32-bit version of the sample program │ │ │ SMPECHO.C │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ ECHO16.MAK │ File that compiles and makes the 16-bit version of the sample program │ │ │ SMPECHO.C │ └────────────────────────┴─────────────────────────────────────────────────────────────────────────┘ ═══ 2.3. Steps for Running SPA Router and ROP Service with IBM LAN Network Manager Version 1.0 or 1.1 ═══ It is assumed that SPA Router and ROP Service have been installed and that LAN Network Manager Version 1.0 or 1.1 has also been installed. If you want to run IBM LAN Network Manager and SPA Router and ROP Service on the same machine, do the following: 1. Stop ROP Service and SPA Router, if they are running. You can do this by issuing the ROP Service STOP command followed by the RTR STOP command. 2. Start LAN Network Manager and configure it to use the OS/2 program as the host option. 3. Stop LAN Network Manager. 4. You can run LAN Network Manager with SPA Router by doing the following: a. Start SPA Router (you can use the RTR START command). b. Start ROP Service (you can use the ROP Service START command). c. Start LAN Network Manager. ═══ 3. SPA Router Commands ═══ This section contains a description of each SPA Router command. The commands are listed in alphabetical order, and the following information is included for each command: o Syntax diagram illustrating how to issue the command o Description of the command parameters and options o Information about using the command o Examples of using the command This section includes the following SPA router commands: RTR RTR APPL RTR CONFIG RTR HELP RTR START RTR STOP RTR TRACE Related Topic: Reading the Command Information ═══ 3.1. Reading the Command Information ═══ When viewing syntax diagrams you can select the highlighted syntax parameters and options to get a description of how the parameters and options function with the command. When applicable, you can also select the highlighted terms Examples and Remarks, which are located under the syntax diagram. When you select these terms you can view examples of how a command is used and get useful remarks describing how a command processes in certain situations. ═══ 3.2. RTR ═══ RTR This command starts SPA Router and brings up the Presentation Manager user interface if that interface is enabled. For information about disabling the Presentation Manager user interface, see RTR CONFIG. Format >>──┬───────┬──┬──────┬── RTR─────────────────────────────────────────────────────────────────────>< └─drive─┘ └─path─┘ Example ═══ <hidden> Example ═══ The following example starts SPA Router if it is not already started. If the user interface is enabled, the SPA Router main window is displayed. RTR ═══ 3.3. RTR APPL ═══ RTR APPL This command displays information about each of the application names currently registered with SPA Router. Deletes selected application names. Format >>──┬───────┬──┬──────┬── RTR APPL──┬──────────────────────────────┬──────────────────────────────>< └─drive─┘ └─path─┘ └─/NAME:applname ─┬─/DELETE─┬──┘ └─/INFO───┘ Examples Remarks ═══ <hidden> /NAME:applname ═══ The name of the application. The length of the name can be from 1 to 8 bytes. Double-byte character set (DBCS) characters are allowed. Note: This option is case sensitive; that is, the name must be typed exactly as it is registered. You can specify /N instead of the complete option name. ═══ <hidden> /DELETE ═══ Deletes from SPA Router the application name specified by applname. You can specify /D instead of the complete option name. ═══ <hidden> /INFO ═══ Displays detailed information about the application name specified by applname. You can specify /I instead of the complete option name. ═══ <hidden> Remarks ═══ o If no options are specified, information about the applications currently registered with SPA Router is displayed. o If the /DELETE option is specified, the application name is closed immediately, which means that the link between SPA Router and the application is closed. The next time the application tries to send a response to SPA Router using that application name, SPA Router returns a message that the name is closed. When the application name is closed, the commands waiting in the receive queue for the application name are discarded, and a message indicating this is returned to the NetView program. Also, any commands being processed by the application are discarded and a message indicating this is returned to the NetView program. Warning: Be careful when deleting application names, because deletion closes the link between the application and SPA Router. Be certain the application is no longer running before deleting an application name. ═══ <hidden> Examples ═══ o The following example displays a list of the application names registered with SPA Router and also displays some information about those applications: RTR APPL The following is an example of the response to this command: Application Registered Waiting In Progress --------------------------------------------------------------- REMOTEOP 11:57:48 AM 21/02/90 3 commands 6 commands LANMGR 04:12:52 PM 23/02/90 1 command 2 commands o The following example displays detailed information for the application name REMOTEOP: RTR APPL /NAME:REMOTEOP /I The following is an example of the response to this command: Application name: REMOTEOP Time of registration: 11:57:48 AM 21/02/90 Receive queue depth: 8 Number of commands waiting: 3 Number of commands being processed: 6 o The following example deletes the application name REMOTEOP: RTR APPL /NAME:REMOTEOP /D The following is an example of the response to this command: Application name REMOTEOP was successfully deleted. ═══ 3.4. RTR CONFIG ═══ RTR CONFIG This command lists and changes the configuration of SPA Router. Format ┌────────────────────────────┐ │ >>──┬───────┬──┬──────┬──RTR CONFIG───┬──────────────────────────┬┴───────────────────────────────>< └─drive─┘ └─path─┘ ├─┬─/HOSTCODEPAGE:─┬──nnn──┤ │ ├─/MAXQDEPTH:────┤ │ │ └─/MAXREGAPP:────┘ │ └─┬─/PM─:───────┬──┬─ON──┬─┘ ├─/TRACEAPI:──┤ └─OFF─┘ └─/TRACEDATA:─┘ Examples Remarks ═══ <hidden> /HOSTCODEPAGE:nnn ═══ Sets the EBCDIC code page number used to translate information to and from the host. The ASCII code page for translation is the current code page of the application process. You can specify /HO instead of the complete option name. Note: All applications using SPA Router use the EBCDIC code page number specified by this option. Initially: The EBCDIC code page for the country as set in the CONFIG.SYS file. For example, for the United States, the value is initially 037; for DBCS systems, the value is initially 939. Possible values: Any valid EBCDIC code page Takes effect: Immediately ═══ <hidden> /MAXQDEPTH:nnn ═══ Specifies the maximum number that can be set as the receive queue depth for an application name. The receive queue depth is the maximum number of commands that can be waiting to be sent by SPA Router to the application. For example, if the maximum queue depth is 10, an application can set the receive queue depth for a name to only 10 or less; it cannot set a receive queue depth greater than 10. If an application does try to set a receive queue depth greater than the maximum queue depth, SPA Router returns a message to the application indicating that the receive queue depth is not allowed, and SPA Router does not allow the application to register the name. You can specify /MAXQ instead of the complete option name. Initially: 32 Possible values: 8 through 32 Takes effect: Immediately ═══ <hidden> /MAXREGAPP:nnn ═══ Sets the maximum number of application names that can be registered with SPA Router. When this maximum is reached, if an application attempts to register a name, SPA Router sends the application a message that the name cannot be registered. In that case, the name can be registered only if the value for the maximum number of registered application names is increased or if an application name currently registered is closed. You can specify /MAXR instead of the complete option name. Initially: 128 Possible values: 1 through 128 Takes effect: Next time SPA Router is started ═══ <hidden> /PM: ═══ Sets the Presentation Manager user interface option on or off. If this option is set to ON, the Presentation Manager user interface is started the next time the RTR command is issued. If this option is set to OFF, the SPA Router main window is not started the next time the RTR command is issued. After this option is turned off, the RTR CONFIG command must be issued using the /PM:ON option to enable the Presentation Manager user interface. Initially: ON Possible values: ON or OFF Takes effect: Next time SPA Router is started ═══ <hidden> /TRACEAPI: ═══ Controls the tracing of SPA Router function calls. If this option is set to ON, SPA Router function calls can be traced. Specifically, when the RTR TRACE /START command is issued, trace information is generated for SPA Router function calls. This information is stored in the trace buffer of Communications Manager. To view this information, copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can then print or view the file. Note: If you have set both the /TRACEAPI and /TRACEDATA options to ON, the information for both is placed in the same trace buffer. See SPA Router Trace Formats, for more information about the trace information. You can specify /TRACEA instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> /TRACEDATA: ═══ Controls the tracing of SPA Router NMVTs. If this option is set to ON, SPA Router NMVTs can be traced. Specifically, when the RTR TRACE /START command is issued, trace information is generated for all NMVTs received and sent by SPA Router. This information is stored in the trace buffer of Communications Manager. To view this information, copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can then print or view the file. Note: If you have set both the /TRACEAPI and /TRACEDATA options to ON, the information for both is placed in the same trace buffer. See SPA Router Trace Formats, for more information about the trace information. You can specify /TRACED instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> Remarks ═══ o If no options are specified, the current configuration settings are displayed. o You can disable the Presentation Manager user interface if you want to run SPA Router without indicating that it is running. Without the Presentation Manager user interface, the screen does not indicate that SPA Router is running because SPA Router runs as a detached process and there is no icon or window displayed. Running SPA Router in this way can help prevent problems caused when someone inadvertently performs SPA Router operations, such as deleting an application name while commands for that name are being processed. ═══ <hidden> Examples ═══ o The following example lists the current SPA Router configuration settings: RTR CONFIG The following is an example of the response to this command: Service Point Application (SPA) Router is configured as follows: Maximum registered application names: 128 Maximum queue depth: 32 EBCDIC code page for NetView: 37 (DBCS systems: EBCDIC code page for NetView: 939) Presentation Manager user interface: ON Trace status: API=ON, DATA=ON; INACTIVE o The following example disables the Presentation Manager user interface, sets the maximum number of concurrent applications to 64, and sets the EBCDIC code page to 37 (for DBCS systems, it is set to 939): RTR CONFIG /MAXREGAPP:64 /HOSTCODEPAGE:37 /PM:OFF (For DBCS systems, /HOSTCODEPAGE:939) The following is an example of the response to this command: SPA Router configuration has been changed successfully. SPA Router is configured as follows: Maximum registered application names: 64 Maximum queue depth: 32 EBCDIC code page for NetView: 37 (DBCS systems: EBCDIC code page for NetView: 939) Presentation Manager user interface: OFF Trace status: API=ON, DATA=ON; INACTIVE The change in the value of the maximum registered applications option will take effect the next time SPA Router is started. ═══ 3.5. RTR HELP ═══ RTR HELP This commands displays help messages for the SPA Router commands. Format >>──┬───────┬──┬──────┬── RTR HELP──┬─────────┬───────────────────────────────────────────────────>< └─drive─┘ └─path─┘ ├─ APPL───┤ ├─ CONFIG─┤ ├─ RTR────┤ ├─ START──┤ ├─ STOP───┤ └─ TRACE──┘ One of the following can be specified: APPL CONFIG RTR START STOP TRACE Examples Remarks ═══ <hidden> Remarks ═══ If an option is not specified, general help information about all SPA Router commands is displayed. ═══ <hidden> Examples ═══ o The following example displays help information about the RTR APPL command: RTR HELP APPL o The following example displays general help information about all SPA Router commands: RTR HELP ═══ 3.6. RTR START ═══ RTR START This command starts the SPA Router without displaying the Presentation Manager (PM) window for the SPA Router. Format ┌────────────────────────────┐ │ >>──┬───────┬──┬──────┬──RTR START───┬──────────────────────────┬┴────────────────────────────────>< └─drive─┘ └─path─┘ ├─┬─/HOSTCODEPAGE:─┬──nnn──┤ │ ├─/MAXQDEPTH:────┤ │ │ └─/MAXREGAPP:────┘ │ └─┬─/PM─:───────┬──┬─ON──┬─┘ ├─/TRACEAPI:──┤ └─OFF─┘ └─/TRACEDATA:─┘ Examples Remarks ═══ <hidden> /HOSTCODEPAGE:nnn ═══ Sets the EBCDIC code page number used to translate information to and from the host. The ASCII code page for translation is the current code page of the application process. You can specify /HO instead of the complete option name. Note: All applications using SPA Router use the EBCDIC code page number specified by this option. Initially: The EBCDIC code page for the country as set in the CONFIG.SYS file. For example, for the United States, the value is initially 037; for DBCS systems, the value is initially 939. Possible values: Any valid EBCDIC code page. Takes effect: Immediately. ═══ <hidden> /MAXQDEPTH:nnn ═══ Specifies the maximum number that can be set as the receive queue depth for an application name. The receive queue depth is the maximum number of commands that can be waiting to be sent by SPA Router to the application. For example, if the maximum queue depth is 10, an application can set the receive queue depth for a name to only 10 or less; it cannot set a receive queue depth greater than 10. If an application does try to set a receive queue depth greater than the maximum queue depth, SPA Router returns a message to the application indicating that the receive queue depth is not allowed and SPA Router does not allow the application to register the name. You can specify /MAXQ instead of the complete option name. Initially: 32 Possible values: 8 through 32 Takes effect: Immediately ═══ <hidden> /MAXREGAPP:nnn ═══ Sets the maximum number of application names that can be registered with SPA Router. When this maximum is reached, if an application attempts to register a name, SPA Router sends the application a message that the name cannot be registered. In that case, the name can be registered only if the value for the maximum number of registered application names is increased or if an application name currently registered is closed. You can specify /MAXR instead of the complete option name. Initially: 128 Possible values: 1 through 128 Takes effect: Immediately ═══ <hidden> /PM: ═══ Sets the Presentation Manager user interface option on or off. If this option is set to ON, the Presentation Manager user interface is started . If this option is set to OFF, the SPA Router main window is not started. After this option is turned off, the RTR CONFIG command must be issued using the /PM:ON option to enable the Presentation Manager user interface. Initially: ON Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> /TRACEAPI: ═══ Controls the tracing of SPA Router function calls. If this option is set to ON, SPA Router function calls can be traced. Specifically, when the RTR TRACE /START command is issued, trace information is generated for SPA Router function calls. This information is stored in the trace buffer of Communications Manager. To view this information, copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can then print or view the file. Note: If you have set both the /TRACEAPI and /TRACEDATA options to ON, the information for both is placed in the same trace buffer. See SPA Router Trace Formats, for more information about the trace information. You can specify /TRACEA instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> /TRACEDATA: ═══ Controls the tracing of SPA Router NMVTs. If this option is set to ON, SPA Router NMVTs can be traced. Specifically, when the RTR TRACE /START command is issued, trace information is generated for all NMVTs received and sent by SPA Router. This information is stored in the trace buffer of Communications Manager. To view this information, copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can then print or view the file. Note: If you have set both the /TRACEAPI and /TRACEDATA options to ON, the information for both is placed in the same trace buffer. See to SPA Router Trace Formats, for more information about the trace information. You can specify /TRACED instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> Remarks ═══ o You can use this command to start SPA Router without starting the Presentation Manager user interface. The screen does not indicate that SPA Router is running because SPA Router runs as a detached process and there is no window or icon displayed. Running SPA Router in this way can help prevent problems caused when someone inadvertently performs SPA Router operations, such as deleting an application name while commands for that name are being processed. o If no configuration options are specified, SPA Router is started using the current configuration settings that were saved the last time SPA Router was run. (The configuration information is saved in the \CMLIB\RTR.INI file.) ═══ <hidden> Examples ═══ o The following example starts SPA Router, if it is not already started: RTR START The following is an example of the response to this command: SPA Router is being started. Please wait. SPA Router is started. The SPA Router is configured as follows: Maximum registered application names: 128 Maximum queue depth: 32 EBCDIC code page for NetView: 37 (DBCS systems: EBCDIC code page for NetView: 939) Presentation Manager user interface: ON Trace status: API=OFF, DATA=OFF; INACTIVE o The following example starts SPA Router with a value of 64 for maximum application names, a value of 16 for the maximum queue depth, and the Presentation Manager user interface enabled: RTR START /MAXREGAPP:64 /MAXQDEPTH:16 /PM:ON The following is an example of the response to this command: SPA Router is being started. Please wait. SPA Router is started. The SPA Router is configured as follows: Maximum registered application names: 64 Maximum queue depth: 16 EBCDIC code page for NetView: 37 (DBCS systems: EBCDIC code page for NetView: 939) Presentation Manager user interface: ON Trace status: API=OFF, DATA=OFF; INACTIVE ═══ 3.7. RTR STOP ═══ RTR STOP This command stops SPA Router without closing the Presentation Manager user interface. Format >>──┬───────┬──┬──────┬── RTR STOP────────────────────────────────────────────────────────────────>< └─drive─┘ └─path─┘ Example Remarks ═══ <hidden> Remarks ═══ When this command is issued, any commands currently being processed are ended immediately. SPA Router returns a response for each command to the NetView program indicating that the command was ended, and SPA Router stops. ═══ <hidden> Example ═══ The following example stops SPA Router: RTR STOP ═══ 3.8. RTR TRACE ═══ RTR TRACE This command configures and controls the tracing of SPA Router function calls and NMVTs. Format >>──┬───────┬──┬──────┬──RTR TRACE──┬─/COPY:filename─┬──────────────┬──────────────────────────┬──>< └─drive─┘ └─path─┘ │ └─/KEYLOCK=key─┘ │ │ ┌────────────────────────┐ │ │ │ │ └─┬─/START─┬──────────────┬──┬───┬──────────────────────┬┴─┘ │ └─/KEYLOCK=key─┘ │ ├─/TRACEAPI:─┬─ON──┬───┤ └─/STOP─┬──────────────┬───┘ │ └─OFF─┘ │ └─/KEYLOCK=key─┘ └─/TRACEDATA:─┬─ON──┬──┘ └─OFF─┘ Examples Remarks ═══ <hidden> /COPY:filename ═══ Copies the trace information from the Communications Manager trace buffer to filename. The trace file created is a text file, which you can view by using the OS/2 TYPE command or by printing the file. You can specify /COP instead of the complete option name. Possible values: Any valid file name, up to 63 bytes in length including drive and path. DBCS characters are allowed. Takes effect: Immediately. ═══ <hidden> /KEYLOCK=key ═══ Unlocks the Communications Manager trace facility. (The trace facility is locked using the keylock option of Communications Manager.) If the Communications Manager trace facility is locked, the /KEYLOCK option must be specified whenever the /START, /STOP, or /COPY option is specified. If a key has not been set up for the Communications Manager trace facility, the /KEYLOCK option does not need to be used. You can specify /K instead of the complete option name. Possible values: 1 through 8 bytes in length. DBCS characters are allowed. Takes effect: Immediately. ═══ <hidden> /START ═══ Starts the selected traces (either function calls, NMVTs, or both). You can specify the traces to start as part of the command by specifying the /TRACEAPI and /TRACEDATA options, or you can start the traces that have been selected previously. (They may already have been selected either through the Presentation Manager user interface or through having specified the /TRACEAPI and /TRACEDATA options when previously issuing the RTR TRACE command, the RTR START command, or the RTR CONFIG command.) You can specify /STA instead of the complete option name. ═══ <hidden> /STOP ═══ Stops all traces. To view the trace information, copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can specify /STO instead of the complete option name. ═══ <hidden> /TRACEAPI: ═══ Controls the tracing of SPA Router function calls. If this option is set to ON, SPA Router function calls can be traced. Specifically, when the RTR TRACE /START command is issued, trace information is generated for SPA Router function calls. This information is stored in the trace buffer of Communications Manager. To view this information, you copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can then print or view the file. Note: If you have set both the /TRACEAPI and /TRACEDATA options to ON, the information for both is placed in the same trace buffer. See SPA Router Trace Formats for more information about the trace information. You can specify /TRACEA instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> /TRACEDATA: ═══ Controls the tracing of SPA Router NMVTs. If this option is set to ON, SPA Router NMVTs can be traced. Specifically, when the RTR TRACE /START command is issued, trace information is generated for all NMVTs received and sent by SPA Router. This information is stored in the trace buffer of Communications Manager. To view this information, copy it from the trace buffer to a file using the RTR TRACE /COPY command. You can then print or view the file. Note: If you have set both the /TRACEAPI and /TRACEDATA options to ON, the information for both is placed in the same trace buffer. See SPA Router Trace Formats, for more information about the trace information. You can specify /TRACED instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> Remarks ═══ o If the Communications Manager trace facility is locked, the /KEYLOCK option must be specified when the /COPY, /START, or /STOP option is specified. o If no options are specified, the current trace settings are displayed. ═══ <hidden> Examples ═══ o The following example turns on and also starts tracing for both function calls and NMVTs. Tracing is started immediately. RTR TRACE /TRACEAPI:ON /TRACEDATA:ON /START The following is an example of the response to this command. The status of ACTIVE indicates the trace has been started. The Traces were successfully started. Trace status: API=ON, DATA=ON; ACTIVE o The following example stops all tracing immediately. Although tracing is stopped, the settings for /TRACEAPI and /TRACEDATA are maintained. RTR TRACE /STOP The following is an example of the response to this command. The status of INACTIVE indicates the trace has been stopped. The Traces were successfully stopped. Trace status: API=ON, DATA=ON; INACTIVE o The following example copies the contents of the trace buffer into the file debug1.trc in directory \trace of the current drive: RTR TRACE /COPY:\trace\debug1.trc ═══ 4. ROP Service Commands ═══ This section contains a description of each ROP Service command. The commands are listed in alphabetical order, and the following information is included for each command: o Syntax diagram illustrating how to issue the command o Description of the command parameters and options o Information about using the command o Examples of using the command This section includes the following ROP Service commands: ROP ROP CMD ROP CONFIG ROP HELP ROP LOG ROP START ROP STOP ROP TABLE ROPSESP ROPSESP STOP ROPSESP HELP Related Topic: Reading the Command Information ═══ <hidden> Reading the Command Information ═══ When viewing syntax diagrams you can select the highlighted syntax parameters and options to get a description of how the parameters and options function with the command. When applicable, you can also select the highlighted terms Examples and Remarks, which are located under the syntax diagram. When you select these terms you can view examples of how a command is used and get useful remarks describing how a command processes in certain situations. ═══ 4.1. ROP ═══ ROP This command starts ROP Service and runs the Presentation Manager user interface for ROP Service if that interface is enabled and not already active in another session. For information about disabling the Presentation Manager user interface, see ROP CONFIG. Format >>──┬───────┬──┬──────┬──ROP──────────────────────────────────────────────────────────────────────>< └─drive─┘ └─path─┘ Example Remarks ═══ <hidden> Remarks ═══ o When you issue the ROP command, the long-running minimum time limit is not applied. o When you issue the ROP command, the time-out limit is not applied. o This command starts the Presentation Manager user interface, if that interface is enabled. If the Presentation Manager user interface is not enabled, ROP Service is started without the Presentation Manager user interface. ═══ <hidden> Example ═══ The following example starts ROP Service, if it is not already started. If the Presentation Manager user interface is enabled, that interface is run. ROP ═══ 4.2. ROP CMD ═══ ROP CMD This command displays information about each of the commands, deletes selected commands, and issues new commands. Format >>──┬───────┬──┬──────┬──ROP CMD──┬─────────┬──┬─┬────────────────────────────────────────┬─┬─────>< └─drive─┘ └─path─┘ └─/NOLOGO─┘ │ └─/CMDID:cmdid─┬─────────┬──┬─────────┬──┘ │ │ ├─/FULL───┤ └─/DELETE─┘ │ │ ├─/OUTPUT─┤ │ │ └─/TERSE──┘ │ └─/START:command─────────────────────────────┘ Examples Remarks ═══ <hidden> /CMDID:cmdid ═══ Specifies the ID of the command. You can specify /CM instead of the full option name. ═══ <hidden> /DELETE ═══ Deletes the specified command. You can specify /DELE instead of the complete option name. ═══ <hidden> /FULL ═══ Prints detailed information about the specified command. You can specify /FUL instead of the complete option name. ═══ <hidden> /NOLOGO ═══ Suppresses the header information when information is displayed; that is, the headings for the columns of information are not displayed; only the information is displayed. You can specify /NOLO instead of the complete option name. ═══ <hidden> /OUTPUT ═══ Displays the response to the specified command. You can specify /OUTP instead of the complete option name. ═══ <hidden> /START:command ═══ Issues the specified command. You can specify /STAR instead of the complete option name. ═══ <hidden> /TERSE ═══ Displays basic information about the specified command. You can specify /TERS instead of the complete option name. ═══ <hidden> Remarks ═══ o When you issue the ROP CMD command, the long-running minimum time limit is not applied. For example, if the time it takes to display the response exceeds the minimum time limit, the response is still displayed. o When you issue the ROP CMD command, the time-out limit is not applied. o If no options are specified, a list of the commands currently being managed is displayed. o /TERSE is the default value for the /CMDID option. If the /CMDID option is specified without specifying any of the options /FULL, /OUTPUT, /TERSE, or /DELE, the same information is displayed as is displayed when /TERSE is specified. o If the /FULL, /OUTPUT, or /TERSE option is specified together with the /DELE option for the /CMDID option, the information requested is displayed and the command is deleted. o If only the /DELE option is specified for the /CMDID option (neither the /FULL, /OUTPUT, nor /TERSE option is specified), then no information is displayed; the command is deleted. o When a command is deleted, it is ended immediately. If the command was issued by the NetView program, a message is sent to the NetView program indicating that the command was ended. ═══ <hidden> Examples ═══ o The following example displays a list of the commands currently being managed by ROP Service: ROP CMD The following is an example of the response to this command: ID Command Started Status Operator WSID ------------------------------------------------------------------------- 0 DISPLAY 1:35:00 PM 10-03-93 Active OPER1 LOCAL_ID 1 PSTAT 1:35:07 PM 10-03-93 Remote OPER1 WS001066 2 CMLINKS 1:35:13 PM 10-03-93 Active OPER2 LOCAL_ID o Each of the following two examples displays information for the command with an ID of 0: ROP CMD /CMDID:0 ROP CMD /CMDID:0 /TERSE The following is an example of the response to these commands: ID Command Started Status Operator WSID ------------------------------------------------------------------------- 0 TYPE 1:41:09 PM 10-03-93 Active OPER1 LOCAL_ID o The following example displays detailed information about the command with an ID of 3: ROP CMD /CMDID:3 /FULL The following is an example of the response to this command: Command ID: 3 Command name: DISPLAY Parameters: Operator ID: OPER2 Time started: 2:15:41 AM 10-03-93 Time finished: -------- Status: Active WSID: LOCAL_ID Output file name: C:\CMLIB\ROPTEMP.003 Process ID: 79 Return code: 0 End processing code: 0 The following is an example of the response to this command if the command is executing on an ESP node: Command ID: 3 Command name: DISPLAY Parameters: Operator ID: OPER2 Time started: 2:19:21 AM 10-03-93 Time finished: -------- Status: Remote WSID: WS001066 Output file name: C:\CMLIB\ROPTEMP.003 Process ID: 79 Return code: 0 End processing code: 0 o The following example displays the response for the command with an ID of 12: ROP CMD /CMDID:12 /OUTPUT o The following example deletes the command whose ID is 9 without first displaying any information about the command: ROP CMD /CMDID:9 /DELETE o The following example issues a command to copy the file FILE.TXT from C:\BIN to C:\BOOK: ROP CMD /START:COPY C:\BIN\FILE.TXT C:\BOOK ═══ 4.3. ROP CONFIG ═══ ROP CONFIG This command lists and changes the configuration of ROP Service. Format ┌────────────────────────────┐ │ >>──┬───────┬──┬──────┬──ROP CONFIG───┬──────────────────────────┬┴───────────────────────────────>< └─drive─┘ └─path─┘ ├─/MAXCMDS:nnn─────────────┤ ├─/MINLR:nnn───────────────┤ ├─/PM─:─┬─ON──┬────────────┤ │ └─OFF─┘ │ ├─/REPLYCODEONLY:─┬─ON──┬──┤ │ └─OFF─┘ │ ├─/TIMEOUT:nnn─────────────┤ ├─/WORKPATH:path───────────┤ ├─/UPM:─┬─ON──┬────────────┤ │ └─OFF─┘ │ └─/ADAPTER:nnn─────────────┘ Examples Remarks ═══ <hidden> /MAXCMDS:nnn ═══ Sets the maximum number of commands that ROP Service can run concurrently. When this limit is reached, subsequent commands are held by SPA Router until ROP Service can accept them. You can specify /MA instead of the complete option name. Initially: 8 Possible values: 1 through 8 Takes effect: Immediately ═══ <hidden> /MINLR:nnn ═══ Sets the long-running minimum time limit, which is the number of seconds of processing time after which a command is detached from the NetView program. The command continues to be processed, but the response is saved on the OS/2 workstation in a temporary file rather than being returned to the NetView program. ROP Service sends a message to the NetView program when the command has completed processing. The NetView operator can display the response to the command by issuing the ROP CMD command. You can specify /MINL instead of the complete option name. Initially: 60 Possible values: 1 through 65535 Takes effect: Immediately ═══ <hidden> /PM: ═══ Sets the Presentation Manager user interface option on or off. If this option is set to ON, then the Presentation Manager user interface is run the next time ROP Service is started. If this option is set to OFF, then the Presentation Manager user interface is not started the next time the ROP command is issued (however, ROP Service is started if it is not already running). After this option is turned off, the ROP CONFIG command must be issued using the /PM:ON option to enable the Presentation Manager user interface. Initially: ON Possible values: ON or OFF Takes effect: Next time ROP Service is started ═══ <hidden> /REPLYCODEONLY: ═══ Sets the format of the response returned to the NetView program. If this option is set to ON, ROP Service returns only the return code. If this option is set to OFF, ROP Service returns the response. You can specify /REPL instead of the complete option name. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> /TIMEOUT:nnn ═══ Sets the number of seconds of processing time after which a command is immediately ended. If the command was issued from the NetView program, a message is sent to the NetView program indicating that the command was ended. You can specify /TIM instead of the complete option name. Initially: 180 Possible values: 1 through 65535 Takes effect: Immediately ═══ <hidden> WORKPATH:path ═══ Sets the path for the working directory, which is the directory where temporary files are stored. You can specify /WOR instead of the complete option name. Initially: \CMLIB on the drive where the system is installed Possible values: Any valid directory path of 3 through 260 characters Takes effect: Immediately ═══ <hidden> /UPM: ═══ Specifies whether the operator ID that issued the command is to be validated using User Profile Management (UPM). If this option is ON, when a command is issued from the NetView program, ROP Service checks that the ID of the NetView operator who issued the command is set up in UPM. If the ID is valid, the command is executed. If the ID is not valid, the command is not executed and a message is returned to the NetView program indicating such. If this option is OFF, the operator ID is not validated with UPM. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> /ADAPTER:nnn ═══ Sets the adapter number to be used for NetBIOS communications with a ROPS extended service point workstation. The adapter must be configured for NetBIOS resources. You can specify /ADAP instead of the full option name. Initially: 0 Possible values: 0 through 255 Takes effect: Next time ROP Service is started ═══ <hidden> Remarks ═══ o When you issue the ROP CONFIG command, the long-running minimum time limit is not applied. o When you issue the ROP CONFIG command, the time-out limit is not applied. o If no options are specified, the current configuration settings are displayed. o You can disable the Presentation Manager user interface if you want to run ROP Service without indicating that it is running. Without the Presentation Manager user interface, the screen does not indicate that ROP Service is running because there is no icon or window displayed. Running ROP Service in this way can help prevent problems caused when someone inadvertently performs ROP Service operations such as deleting a command while it is still processing. ═══ <hidden> Examples ═══ o The following example lists the current ROP Service configuration settings: ROP CONFIG The following is an example of the response to this command: Remote Operations Service Configuration Information Work Path: C:\CMLIB NetView application name: REMOTEOP Command table name: C:\CMLIB\CMDTBL.ROP Maximum concurrent commands: 4 Minimum long-running time (in seconds): 50 Command timeout (in seconds): 400 Presentation Manager display: ON Return with reply code only: OFF UPM operator checking: ON NetBIOS adapter number: 0 o The following example disables the Presentation Manager user interface for the next invocation of ROP Service, sets the maximum number of concurrent commands to 6, and defines the response to the NetView program as reply code only: ROP CONFIG /PM:OFF /MAXCMDS:6 /REPLYCODEONLY:ON o The following example sets the path for the working directory to D:\ROPWRK: ROP CONFIG /WORKPATH:D:\ROPWRK o The following example sets the long-running minimum time to 2 minutes and the maximum time for which a command can execute before it is automatically ended to 4 minutes: ROP CONFIG /MINLR:120 /TIMEOUT:240 ═══ 4.4. ROP HELP ═══ ROP HELP This command displays help messages for the ROP Service commands. Format ┌──────────┐ │ >>──┬───────┬──┬──────┬──ROP HELP───┬────────┬┴───────────────────────────────────────────────────>< └─drive─┘ └─path─┘ ├─CMD────┤ ├─CONFIG─┤ ├─LOG────┤ ├─START──┤ ├─STOP───┤ └─TABLE──┘ One of the following can be specified: CMD CONFIG LOG START STOP TABLE Examples Remarks ═══ <hidden> Remarks ═══ o When you issue the ROP HELP command, the long-running minimum time limit is not applied. o When you issue the ROP HELP command, the time-out limit is not applied. o If an option is not specified, general help information about all ROP Service commands is displayed. ═══ <hidden> Examples ═══ o The following example displays help information about the ROP CMD command: ROP HELP CMD o The following example displays general help information about all ROP Service commands: ROP HELP ═══ 4.5. ROP LOG ═══ ROP LOG This command lists and changes the settings for logging commands that ROP Service attempts to execute. Format ┌─────────────────────┐ │ >>──┬───────┬──┬──────┬──ROP LOG───┬───────────────────┬┴─────────────────────────────────────────>< └─drive─┘ └─path─┘ ├─/ENABLE:─┬─ON──┬──┤ │ └─OFF─┘ │ └─/MAXFILESIZE:nnn──┘ Examples ═══ <hidden> ENABLE: ═══ Specifies whether logging is on or off. If this option is ON, each command that ROP Service attempts to execute is logged. If this option is OFF, no commands are logged. Initially: OFF Possible values: ON or OFF Takes effect: Immediately ═══ <hidden> MAXFILESIZE:nnn ═══ Specifies the maximum size allowed for the log file. When this file size is reached, subsequent commands are recorded starting at the beginning of the file, thus erasing any commands that were at the beginning. You can specify /MA instead of the complete option name. Initially: 50000 bytes Possible values: 1 through 4294967295 bytes (4.2 gigabytes) Takes effect: Immediately, if the new value is greater than the current file size (the actual file size, not the maximum allowed file size). If the new value is less than the current file size, it takes effect the next time ROP service is started. ═══ <hidden> Examples ═══ o The following example lists the current logging settings: ROP LOG The following is an example of the response to this command: Remote Operations Service Logging Options Maximum Filesize: 50000 Enabled: ON o The following example turns logging off and sets the maximum file size to 1MB: ROP LOG /ENABLE:OFF /MAXFILESIZE:1000000 The following is an example of the response to this command: Remote Operations Service Logging Options Maximum Filesize: 1000000 Enabled: OFF ═══ 4.6. ROP START ═══ ROP START This command starts ROP Service and runs the Presentation Manager user interface for ROP Service, if that interface is enabled and if it is not already active in another session. For information about disabling the Presentation Manager user interface, see ROP CONFIG. The difference between the ROP START command and the ROP command is that the ROP command automatically switches to the Presentation Manager main window for ROP Service. The ROP START command remains at the OS/2 session. Format >>──┬───────┬──┬──────┬──ROP START──┬───────────┬─────────────────────────────────────────────────>< └─drive─┘ └─path─┘ └─/FULLSIZE─┘ Examples Remarks ═══ <hidden> /FULLSIZE ═══ Specifies that ROP Service should be displayed in a window when it is started rather than being displayed as an icon. You can specify /FULL instead of the complete option name. ═══ <hidden> Remarks ═══ If you issue this command without any options, it starts a session that runs ROP Service and displays ROP Service as an icon, which you can select to display the ROP Service main window. ═══ <hidden> Examples ═══ The following example starts ROP Service, if it is not already started, and displays the session as an icon: ROP START The following is an example of the response to this command: Remote Operations Service is being started. Please wait. Remote Operations Service is started. ═══ 4.7. ROP STOP ═══ ROP STOP This command stops ROP Service. Format >>──┬───────┬──┬──────┬──ROP STOP─────────────────────────────────────────────────────────────────>< └─drive─┘ └─path─┘ Example Remarks ═══ <hidden> Remarks ═══ o When you issue the ROP STOP command, the long-running minimum time limit is not applied. o When you issue the ROP STOP command, the time-out limit is not applied. o When this command is issued, all commands are deleted, ROP Service returns a response to the NetView program for each command indicating that the command was ended, and ROP Service stops. ═══ <hidden> Example ═══ The following example stops ROP Service: ROP STOP ═══ 4.8. ROP TABLE ═══ ROP TABLE Purpose Adds commands to the command validation table, deletes commands from the command validation table, and modifies the exclusive set option. Format >>──┬───────┬──┬──────┬──ROP TABLE──┬─────────────────┬──┬──────────────────────┬─────────────────>< └─drive─┘ └─path─┘ ├─/ADD:command────┤ └─/EXCLUSIVE:─┬─ON──┬──┘ └─/DELETE:command─┘ └─OFF─┘ Examples Remarks ═══ <hidden> /ADD:command ═══ Adds the command to the command validation table, where command is an OS/2 command name. Since only the command name is used in the table, you do not need to specify the path, parameters, or options. ═══ <hidden> /DELETE:command ═══ Deletes the command from the command validation table, where command is an OS/2 command name. You can specify /DELE instead of the complete option name. ═══ <hidden> /EXCLUSIVE: ═══ Specifies whether the command validation list is exclusive (none of the commands in the list can be executed through ROP Service) or inclusive (only those commands in the list can be executed through ROP Service). If this option is set to ON, the list is exclusive. If this option is set to OFF, the list is inclusive. You can specify /EXCL instead of the complete option name. Initially: ON Takes effect: Immediately ═══ <hidden> Remarks ═══ o When you issue the ROP TABLE command, the long-running minimum time limit is not applied. o When you issue the ROP TABLE command, the time-out limit is not applied. o If no options are specified, the command validation table is displayed. ═══ <hidden> Examples ═══ o The following example adds the command TYPE to the command validation table: ROP TABLE /ADD:TYPE o The following example deletes the command TYPE from the command validation table: ROP TABLE /DELETE:TYPE o The following example sets the exclusive option on: ROP TABLE /EXCLUSIVE:ON ═══ 4.9. ROPSESP ═══ ROPSESP This command starts ROPS ESP. Format >>──┬───────┬──┬──────┬──ROPSESP──┬─────────────────────────┬─────────────────────────────────────>< └─drive─┘ └─path─┘ └─START──┬──────────────┬─┘ └─/ADAPTER:nnn─┘ Examples Remarks ═══ <hidden> START ═══ START is an optional parameter. It has the same effect as issuing ROPSESP alone. ═══ <hidden> /ADAPTER:nnn ═══ Sets the adapter number to be used for NetBIOS communications with a ROPS service point workstation. The adapter must be configured for NetBIOS resources. Initially: 0 Possible values: 0 through 255 Takes effect: Immediately ═══ <hidden> Remarks ═══ o If ROPS ESP is already started on the work station and a start command is issued, the error message "ROPS ESP is already started." is issued. o If the name ROPS ESP attempts to add to the NetBIOS table is not unique, the message "ROPS ESP encountered a problem while attempting to start." is issued. ═══ <hidden> Examples ═══ The following example starts ROPSESP: ROPSESP The following example starts ROPSESP with NetBIOS communications using adapter 1: ROPSESP START /ADAPTER:1 The following is an example of the response to both of the commands above: Remote Operations Service Extended Service Point is being started. Please wait. Remote Operations Service Extended Service Point is started. ═══ 4.10. ROPSESP STOP ═══ ROPSESP STOP This command stops ROPS ESP. Format >>──┬───────┬──┬──────┬──ROPSESP STOP─────────────────────────────────────────────────────────────>< └─drive─┘ └─path─┘ Examples Remarks ═══ <hidden> Remarks ═══ If ROPS ESP is not started and a stop command is issued, the error message "ROPS ESP is not started." is issued. ═══ <hidden> Examples ═══ The following example stops ROPSESP: ROPSESP STOP The following is an example of the response to this command: Remote Operations Service Extended Service Point is being stopped. Remote Operations Service Extended Service Point is stopped. ═══ 4.11. ROPSESP HELP ═══ ROPSESP HELP This commands displays help messages for the ROPS ESP commands. Format >>──┬───────┬──┬──────┬── ROPSESP HELP──┬──────────┬──────────────────────────────────────────────>< └─drive─┘ └─path─┘ ├─ ROPSESP─┤ ├─ START───┤ └─ STOP────┘ One of the following can be specified: ROPSESP START STOP Examples Remarks ═══ <hidden> Remarks ═══ If an option is not specified, general help information about all ROPS ESP commands is displayed. ═══ <hidden> Examples ═══ o The following example displays help information about the ROPSESP START command: ROPSESP HELP START o The following example displays general help information about all ROPSESP commands: ROPSESP HELP ═══ 5. Developing REXX Executable Files and CLISTs ═══ Developing REXX Executable Files and CLISTs The NetView program can be customized for use with SPA Router and ROP Service through REXX executable files (execs) and command lists (CLISTs). REXX execs and CLISTs allow ROP Service commands to be issued automatically, that is, without the need to manually enter each command. In addition, REXX execs and CLISTs provide a wide range of capability; they can perform functions on one workstation alone as well as perform functions on all LANs in the enterprise. Plus, REXX execs can be placed within other REXX execs or other higher level programs to provide even more complex functions. This is also true for CLISTs. For more information, select one of the following: REXX execs CLISTs Note: The REXX execs and CLISTs in this chapter were developed using NetView Customization Guide, which you may find useful when developing your own REXX execs and CLISTs. The guide does, however, assume a working knowledge of REXX. Related Topic: Handling the Time before Setting Status to Long-Running ═══ 5.1. Handling the Long-Running Minimum Time Limit ═══ When a command exceeds the long-running minimum time limit, ROP Service sends a message to the REXX exec or CLIST indicating that the command has exceeded the limit. This message is a solicited one because it is returned in response to a RUNCMD issued by the REXX exec or CLIST. The command then completes processing on the OS/2 workstation, and the response is saved in a temporary file on the OS/2 workstation. The response is not returned to the REXX exec or CLIST. The command may also time out or be deleted before it is finished processing. In any case, a message is returned to the REXX exec or CLIST indicating the final status of the command (finished, timed out, or deleted). This second message is an unsolicited message. REXX execs and CLISTs cannot process unsolicited messages. Thus, the REXX exec or CLIST cannot notify the user of the final status of the command. But, the REXX exec or CLIST can notify the user that the command has a long-running status (because the message about the long-running status is a solicited message that the REXX exec or CLIST can process). Consequently, REXX execs and CLISTs should be written to process either the command response or notification that a command has a long-running status. The REXX exec or CLIST can determine which is the case by examining the output header that is returned for each command. If the REXX exec or CLIST receives the command response, the information can be processed accordingly. However, if the REXX exec or CLIST receives notification that the command has a long-running status, the REXX exec or CLIST can log that information. When the REXX exec or CLIST has finished running, the user can view the log. The user can then issue a ROP command to determine the final status of the command that was long-running and retrieve the response. ═══ 5.2. REXX Execs ═══ When developing REXX execs, be particularly careful about how you handle the 04 return code. The 04 return code can indicate several kinds of failure, such as SSCP-PU session busy and target physical unit (PU) is not activated. Since the 04 return code covers several situations, you should consider how the exec will be used when determining how to handle this return code. In particular, it is recommended that you do not use an infinite loop to retry the operation for which a 04 return code is received (even though the 04 return code means that the operation can be retried). The REXX execs in this chapter demonstrate useful network control functions. They are meant to be used as examples in the development of company-specific execs. Error checking, file handling, and screen input and output are supplementary features, and functions for those processes would unnecessarily complicate the execs. Thus, the following execs contain only the code necessary to demonstrate ROP Service commands. Select one of the following REXX execs for more information: The following REXX execs are included in this chapter: ADDUSER Adds a user to multiple LANs within the enterprise DELUSER Deletes a user from all LANs QNAME Identifies on which LANs a user has a logon account QUSERS Identifies all of the users on the LANs SAVEENV Saves the current values of the ROP Service configuration options, changes those options to new values, and then resets the options to their original values To invoke a REXX exec, you type the exec name followed by any parameters that may be required. For example, to invoke the ADDUSER exec, you type ADDUSER userid password. ═══ 5.2.1. ADDUSER REXX Exec ═══ The ADDUSER exec adds to multiple LANs within the company the user and password specified when the exec is invoked. To add a user, ROP Service needs to know to which domain controller (as specified by the PU) to add the user, the LAN administrator ID for that domain controller, and the password for the ID. This information is coded into the ADDUSER exec. However, the information could be accessed from a file. The ADDUSER exec sends NetView RUNCMDs to each PU identified in the exec. One RUNCMD is sent with instructions to access the LAN with an administrator logon ID. When this is accomplished, the user is added to this LAN and the administrator ID is logged off. This process is repeated for each PU listed in the exec. To invoke the exec, type the following: ADDUSER userid password. The ID and password of the user to be added are required parameters. The ADDUSER REXX exec is written as follows: /* ADDUSER */ /* Command to add user to multiple LANS */ /* Input arguments: */ /* 1. User name */ /* 2. User password */ /* Outputs: */ /* 1. Completion results */ /* */ /* */ /* trace ?i */ /* trace ?i */ execname = 'adduser' nvop=OPID() arg user_name user_password if user_name = "" then signal HELPCM networks=1 /* number of networks to cycle thru */ /* Structure is: */ /* network_pu(networks) */ /* 1st member: administrator ID */ /* 2nd member: administrator password */ /* */ /* */ network_pu.1=thx350 network_pu.1.admin=ropadmin network_pu.1.passw="" /* next element network_pu.2=?????? network_pu.2.admin=???????? network_pu.2.passw="" */ /* Main Loop */ do i = 1 to networks /* set reply with return code only */ base = 'RUNCMD SP='||network_pu.i||',APPL=REMOTEOP,CLISTVAR=YES,' basecm = base||'OP='||nvop';' longrcm = basecm||'rop config /minlr:300 /timeout:600' say longrcm longrcm say DSIRUN001 replycm = basecm||'rop config /replycodeonly:on' say replycm replycm say DSIRUN001 /* if no error */ /* logon to network as administrator */ logcm1 = basecm||'c:\muglib\logon ' logcm2 = logcm1||network_pu.i.admin||' '||network_pu.i.passw say logcm2 logcm2 say DSIRUN001 call CKLOGERR /* if no error */ if result = 0 then do addcm1 = basecm||'net user '||user_name||' ' addcm2 = addcm1||user_password||' /add' say addcm2 addcm2 say DSIRUN001 call CKADDERR /* if no error */ logoffcm = basecm||'c:\muglib\logoff ' say logoffcm logoffcm say DSIRUN001 end /* set reply with return code only to off */ replycm2 = basecm||'rop config /replycodeonly:off' say replycm2 replycm2 say DSIRUN001 end exit CKADDERR: /* if no error */ say "DSIRUN001 = "||DSIRUN001 if substr( DSIRUN001, 1, 49 ) ==, "NET The process has completed with return code 0" then return 0 say "Add user error " return -1 CKLOGERR: /* if no error */ if substr( DSIRUN001, 1, 61 ) ==, "C:\MUGLIB\LOGON The process has completed with return code 0" then return 0 say "Logon error " return -1 HELPCM: say 'You must enter a user name to be added to all networks' exit Example ═══ <hidden> Example of ADDUSER exec ═══ The following example displays the output from the ADDUSER exec: ADDUSER LINDA ROPSFUN RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;rop config /minlr:300/timeout:600 Start of Output [THX350 ] ROP CONFIG /MINLR:300 /TIMEOUT:600 RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;rop config /replycodeonly:on ROP The process has completed with return code 0. RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;c:\muglib\logon ROPADMIN C:\MUGLIB\LOGON The process has completed with return code 0. RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;c:\ibmlan\netprog\net user LINDA ROPSFUN /add NET The process has completed with return code 0. DSIRUN001 = C:\IBMLAN\NETPROG\NET Finished. Return code = 0 RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;c:\muglib\logoff C:\MUGLIB\LOGOFF The process has completed with return code 0. RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11:rop config /replycodeonly:off ═══ 5.2.2. DELUSER REXX Exec ═══ The function of the DELUSER exec is exactly the opposite of that of the ADDUSER exec. The DELUSER exec deletes the user ID specified when the exec is invoked. It deletes the user ID from the LANs listed in the exec. As with the ADDUSER exec, the DELUSER exec contains a list of domain controllers (specified by PU) from which to delete the user, administrator IDs for those domain controllers, and the passwords for each ID. RUNCMDs are sent to each LAN. These commands log on to the LAN, delete the user, and then log off of the LAN. To invoke the DELUSER exec, type the following: DELUSER userid Only the ID of the user to be deleted is required as a parameter. The DELUSER REXX exec is written as follows: /* DELUSER */ /* Command to delete user from multiple LANS */ /* Input arguments: */ /* 1. User name */ /* Outputs: */ /* 1. Completion results */ /* */ /* */ /* trace ?i */ /* trace ?i */ execname = 'deluser' nvop=OPID() user_name="" arg user_name if user_name = "" then signal HELPCM networks=1 /* number of networks to cycle thru */ /* Structure is: */ /* network_pu(networks) */ /* 1st member: administrator ID */ /* 2nd member: administrator password */ /* */ /* */ network_pu.1=thx350 network_pu.1.admin=ropadmin network_pu.1.passw="" /* next element network_pu.2=?????? network_pu.2.admin=???????? network_pu.2.passw="" */ /* Main Loop */ do i = 1 to networks /* set reply with return code only */ base = 'RUNCMD SP='||network_pu.i||',APPL=REMOTEOP,CLISTVAR=YES,' basecm = base||'OP='||nvop';' longrcm = basecm||'rop config /minlr:300 /timeout:600' say longrcm longrcm say DSIRUN001 replycm = basecm||'rop config /replycodeonly:on' say replycm replycm say DSIRUN001 /* if no error */ /* logon to network as administrator */ logcm1 = basecm||'c:\muglib\logon ' logcm2 = logcm1||network_pu.i.admin||' '||network_pu.i.passw say logcm2 logcm2 say DSIRUN001 call CKLOGERR /* if no error */ if result = 0 then do delcm1 = basecm||'net user '||user_name||' ' delcm2 = delcm1||' /del' say delcm2 delcm2 say DSIRUN001 call CKDELERR /* if no error */ logoffcm = basecm||'c:\muglib\logoff ' say logoffcm logoffcm say DSIRUN001 end /* set reply with return code only to off */ replycm2 = basecm||'rop config /replycodeonly:off' say replycm2 replycm2 say DSIRUN001 end exit CKDELERR: /* if no error */ if substr( DSIRUN001, 1, 49 ) ==, "NET The process has completed with return code of 0" then return 0 say "Delete user error " return -1 CKLOGERR: /* if no error */ if substr( DSIRUN001, 1, 61 ) ==, "C:\MUGLIB\LOGON The process has completed with return code of 0" then return 0 say "Logon error " return -1 HELPCM: say 'You must enter a user name to be deleted from all networks' exit ═══ 5.2.3. QNAME REXX Exec ═══ The QNAME exec performs a query of all the LANs listed in the exec and identifies on which LANs a user has a logon account. You specify the user when you invoke the exec. To perform the query, the QNAME exec contains a list of the domain controllers (specified by PU) to query, administrator IDs for those domain controllers, and the passwords for each administrator ID. To invoke the QNAME exec, type the following: QNAME userid Only the ID of the user whose accounts are to be identified is required as a parameter. The QNAME REXX exec is written as follows: /* QNAME */ /* Command to query users for multiple LANS */ /* Input arguments: */ /* 1. User name */ /* Outputs: */ /* 1. Completion results */ /* */ /* */ /* trace ?i */ /* trace ?i */ execname = 'qname' nvop=OPID() arg user_name if user_name = "" then signal HELPCM user_name = translate(user_name) /* uppercase */ networks=1 /* number of networks to cycle thru */ /* Structure is: */ /* network_pu(networks) */ /* 1st member: administrator ID */ /* 2nd member: administrator password */ /* */ /* */ network_pu.1=thx350 network_pu.1.admin=ropadmin network_pu.1.passw="" /* next element network_pu.2=?????? network_pu.2.admin=???????? network_pu.2.passw="" */ /* Main Loop */ do i = 1 to networks /* set reply with return code only */ base = 'RUNCMD SP='||network_pu.i||',APPL=REMOTEOP,CLISTVAR=YES,' basecm = base||'OP='||nvop';' longrcm = basecm||'rop config /minlr:300 /timeout:600' say longrcm longrcm say DSIRUN001 replycm = basecm||'rop config /replycodeonly:on' say replycm replycm say DSIRUN001 /* if no error */ /* logon to network as administrator */ logcm1 = basecm||'c:\muglib\logon ' logcm2 = logcm1||network_pu.i.admin||' '||network_pu.i.passw say logcm2 logcm2 say DSIRUN001 call CKLOGERR /* set reply with return code only to off */ replycm2 = basecm||'rop config /replycodeonly:off' say replycm2 replycm2 say DSIRUN001 if result = 0 then /* from cklogerr */ do querycm = basecm||'net users' say querycm querycm do n = 4 to DSIRUNCNT /* Note responses are in DSIRUNxxx where xxx varies from 001 to the value of DSIRUNCNT. */ unames = value( 'DSIRUN' || right(n,3,'0') ) /* say unames */ do x = 1 to 3 /* length(unames) */ /* say user_name||' compared to '||subword(unames,x,1) */ if user_name == subword(unames,x,1) then do say user_name||' is a user in '||network_pu.i leave /* n = DSIRUNCNT */ end end end logoffcm = basecm||'c:\muglib\logoff ' say logoffcm logoffcm say DSIRUN001 end end exit CKLOGERR: /* if no error */ if substr( DSIRUN001, 1, 61 ) ==, "C:\MUGLIB\LOGON The process has completed with return code of 0" then say "Logon error " return -1 HELPCM: say 'You must enter a user name to be checked to all networks' exit ═══ 5.2.4. QUSERS REXX Exec ═══ The QUSERS exec identifies all of the users on the LANs listed in the exec. To do this, the exec contains a list of the domain controllers (specified by PU) to query, of administrator IDs for those domain controllers, and the passwords for each administrator ID. To invoke the QUSERS exec, type the following: QUSERS No parameters are required. The QUSERS REXX exec is written as follows: /* QUSERS */ /* Command to query users for multiple LANs */ /* Input arguments: */ /* *** none *** */ /* Outputs: */ /* 1. Completion results */ /* 2. Lists of users */ /* */ /* */ /* trace ?i */ /* trace ?i */ execname = 'qusers' nvop=OPID() user_name="" networks=1 /* number of networks to cycle thru */ /* Structure is: */ /* network_pu(networks) */ /* 1st member: administrator ID */ /* 2nd member: administrator password */ /* */ /* */ network_pu.1=thx350 network_pu.1.admin=ropadmin network_pu.1.passw="" /* next element network_pu.2=?????? network_pu.2.admin=???????? network_pu.2.passw="" */ /* Main Loop */ do i = 1 to networks /* set reply with return code only */ base = 'RUNCMD SP='||network_pu.i||',APPL=REMOTEOP,CLISTVAR=YES,' basecm = base||'OP='||nvop';' longrcm = basecm||'rop config /minlr:300 /timeout:600' say longrcm longrcm say DSIRUN001 replycm = basecm||'rop config /replycodeonly:on' say replycm replycm say DSIRUN001 /* if no error */ /* logon to network as administrator */ logcm1 = basecm||'c:\muglib\logon ' logcm2 = logcm1||network_pu.i.admin||' '||network_pu.i.passw say logcm2 logcm2 say DSIRUN001 call CKLOGERR /* set reply with return code only to off */ replycm2 = basecm||'rop config /replycodeonly:off' say replycm2 replycm2 say DSIRUN001 if result = 0 then /* from cklogerr */ do querycm = basecm||'net users' say querycm querycm do i = 1 to DSIRUNCNT /* Note responses are in DSIRUNxxx where xxx varies from 001 to the value of DSIRUNCNT. */ say value( 'DSIRUN' || right(i,3,'0') ) end logoffcm = basecm||'c:\muglib\logoff ' say logoffcm logoffcm say DSIRUN001 end end exit CKLOGERR: /* if no error */ if substr( DSIRUN001, 1, 61 ) ==, "C:\MUGLIB\LOGON The process has completed with return code 0" then return 0 say "Logon error " return -1 Example ═══ <hidden> Example of QUSERS REXX Exec ═══ The following example displays the output from the QUSERS exec: QUSER RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;rop config /minlr:300/timeout:600 Start of Output [THX350 ] ROP CONFIG /MINLR:300 /TIMEOUT:600 RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;rop config /replycodeonly:on ROP The process has completed with return code 0. RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;c:\muglib\logon ROPADMIN C:\MUGLIB\LOGON The process has completed with return code 0. RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11; rop config /replycodeonly:off Start of Output [THX350 ] ROP CONFIG /REPLYCODEONLY:OFF RUNCMD SP=THX350A,APPL=REMOTEOP,CLISTVAR=YES,OP=ROPS015;net users Start of Output [THX350 ] NET USERS User accounts for \\ROP70 ------------------------------------------------------------------------- BRIAN DAVID LINDA ROP70 SIDE1 SVTL13 USERID The command completed successfully. End of Output [THX350] NET USER RUNCMD SP=THX350,APPL=REMOTEOP,CLISTVAR=YES,OP=SVTL11;c:\muglib\logoff Start of Output [THX350 ] C:\MUGLIB\LOGOFF ------------------------------------------------------------------------- ═══ 5.2.5. SAVEENV REXX Exec ═══ The SAVEENV exec saves the current values of the ROP Service configuration options, resets those options to new values, and then restores the options to their original values (the ones saved at the start of the exec). The SAVEENV exec is not meant to be used as is; rather, it is provided as an example to be used when developing an exec that changes and restores the ROP Service configuration options. To invoke the SAVEENV exec, type the following: SAVEENV No parameters are required. The SAVEENV REXX exec is written as follows: /* SAVEENV */ /* Command to save environment of remote operations for PC */ /* Input arguments: */ /* 1. None */ /* Outputs: */ /* 1. Completion results */ /* 2. User information */ /* */ /* trace ?i */ /* trace ?i */ execname = 'saveenv' nvop=OPID() networks=1 /* number of networks to cycle thru */ /* Structure is: */ /* network_pu(networks) */ /* 1st member: administrator ID */ /* 2nd member: administrator password */ /* */ /* */ network_pu.1=thx350 network_pu.1.admin=ropadmin network_pu.1.passw="" /* next element network_pu.2=?????? network_pu.2.admin=???????? network_pu.2.passw="" */ /* Main Loop */ do i = 1 to networks say 'Saving some ROP configuration options' base = 'RUNCMD SP='||network_pu.i||',APPL=REMOTEOP,CLISTVAR=YES,' basecm = base||'OP='||nvop';' longrcm = basecm||'rop config' say longrcm longrcm do n = 3 to 12 say value(DSIRUN00||n) end wkp = substr( DSIRUN004, 42) mxc = substr( DSIRUN007, 42) mnl = substr( DSIRUN008, 42) mxl = substr( DSIRUN009, 42) pmf = substr( DSIRUN010, 42) rco = substr( DSIRUN011, 42) say 'Setting some ROP configuration options' setcm = 'RUNCMD SP='||network_pu.i||',APPL=REMOTEOP,OP='||nvop';' replycm = setcm||'rop config /replycodeonly:on /maxcmds:5' say replycm replycm replycm = setcm||'rop config /minlr:333 /timeout:777' say replycm replycm replycm = setcm||'rop config /workpath:c:\cmlib' say replycm replycm replycm = setcm||'rop config /pm:off' say replycm replycm say longrcm longrcm do n = 3 to 12 say value(DSIRUN00||n) end say 'Restoring some ROP configuration options' replycm = setcm||'rop config /replycodeonly:'||rco||' /maxcmds:'||mxc say replycm replycm replycm = setcm||'rop config /minlr:'||mnl||' /timeout:'||mxl say replycm replycm replycm = setcm||'rop config /workpath:'||wkp say replycm replycm replycm = setcm||'rop config /pm:'||pmf say replycm replycm say longrcm longrcm do n = 3 to 12 say value(DSIRUN00||n) end end exit ═══ 5.3. CLISTs ═══ The CLIST included in this chapter is used to reduce the keystrokes required to issue RUNCMD commands to the same service point and application name. Specifically, the CLIST allows the NetView operator to enter the service point PU and application name once and then use those values as defaults for subsequent commands that are issued. This CLIST uses the VIEW command of the NetView program and also illustrates the panel processing capability provided by the NetView program. The panel processing capability is demonstrated by two help panels. The first time you invoke this CLIST, type the parameters for the PU and the application name along with the command that is to be sent to SPA Router as follows: ROP SP=puname, APPL=applname, OS/2command For subsequent executions of this CLIST, type only ROP followed by the command parameter, as follows: ROP OS/2command The first help panel is displayed when an error is typed or when no parameters are specified. It provides information about the syntax that must be used. The second panel contains more detailed information about the syntax as well as several examples. The second help panel is accessed from the first help panel by typing a 1. Program function (PF) key selections are provided to exit the help panels or to perform other standard NetView operations like ROLL. Select one of the following for more information: ROP CLIST CNMKROP help panel CNM1ROP help panel The help panels must be installed in panel data set DDNAME CNMPNL1 (for MVS) or in a file with file type NCCFLST (for VM). ═══ 5.3.1. ROP CLIST ═══ The following is the ROP CLIST: CLIST &CONTROL ERR &TGLOBAL SP,AP &R = &PARMSTR PARSEL2R R /SP=/ R1 R2 PARSEL2R R1 XSP /,/ R3 PARSEL2R R /APPL=/ R1 R2 PARSEL2R R1 XAP /,/ R3 &IF .&XSP ^= . &THEN &SP = &XSP &IF .&XAP ^= . &THEN &AP = &XAP &IF .&SP = . &THEN &SP = ? &IF .&AP = . &THEN &AP = ? &IF .&SP = .? &THEN &DSP = '^Not defined' &IF .&AP = .? &THEN &DAP = '^Not defined' &IF .&SP ^= .? &THEN &DSP = &CONCAT '>' &SP &IF .&AP ^= .? &THEN &DAP = &CONCAT '>' &AP &IF .&SP = .? &THEN &GOTO -HELP &IF .&AP = .? &THEN &GOTO -HELP &IF .&1 = .? &THEN &GOTO -HELP &IF &PARMCNT = 0 &THEN &GOTO -HELP PARSEL2R R R1 /%/ R2 &IF .&R2 ^= . &THEN &MSG = ' "% is not allowed in SPCF commands.' &IF .&R2 ^= . &THEN &R = &CONCAT &R1 '"%' &IF .&R2 ^= . &THEN &R = &CONCAT &R &R2 &IF .&R2 ^= . &THEN &GOTO -HELP PARSEL2R R /;/ R1 &IF .&R1 ^= . &THEN &MSG = ' ; is not allowed in SPCF commands.' &IF .&R1 ^= . &THEN &GOTO -HELP PARSEL2R R R4 /,/ R5 /,/ R6 &IF .&R6 ^= . &THEN &OS2 = &R6 &IF .&R6 ^= . &THEN &GOTO -OS2CMD &IF .&R5 ^= . &THEN &OS2 = &R5 &IF .&R5 ^= . &THEN &GOTO -OS2CMD &IF .&R4 ^= . &THEN &OS2 = &R4 &IF .&R4 ^= . &THEN &GOTO -OS2CMD &GOTO -HELP -OS2CMD RUNCMD SP=&SP,APPL=&AP,OP=&OPID;&OS2 &EXIT -USERFUNC RUNCMD SP=&SP,APPL=&AP,70;SET REQOP=&OPID + ;ECHO USER DEFINED FUNCTION NOT YET DEFINED. &EXIT -HELP &IF .&SP = .? &THEN &MSG = 'Service Point and/or APPLication + parameters have not been specified.' &IF .&AP = .? &THEN &MSG = 'Service Point and/or APPLication + parameters have not been specified.' &PROMPT = 'OS2' &IF .&SP = .? &THEN &PROMPT = &CONCAT &PROMPT ' SP=? ' &IF .&AP = .? &THEN &PROMPT = &CONCAT &PROMPT ' APPL=? ' &IF .&R = .? &THEN &R = '' &IF .&PROMPT = .ROP &THEN &PROMPT = &CONCAT 'ROP ' &R &IF .&R = . &THEN &PROMPT = '' VIEW 4 CNMKROP &EXIT ═══ 5.3.2. CNMKROP Help Panel ═══ The following is the CNMKROP help panel: /* DESCRIPTION: MENU FOR OS/2 CLIST (COMMUNICATE WITH ROP SERVICE) * 1 CNM1ROP Prompt for OS2 command *** +CNMKROP %Send commands to OS/2 Remote Operations Service $ +Current Service Point:&DSP +Current Application:&DA $ $ \Syntax:$ %ROP SP=pu_name,APPL=spcf_appl_name,os2_command $ $The SP= and APPL= parameters may be omitted. They will default to values $used on previous invocations. A space may be used instead of a comma to $separate parameters. Always enter the OS/2 command as the last parameter. $ $ $ $ $ $ $ $ $ $Enter command or select (1) for additional information and examples: Ы&MSG %===>°&PROMPT $ $ PF2= End PF3= Return PF6= Roll PF7= Backward PF11= Entry Point ═══ 5.3.3. CNM1ROP Help Panel ═══ The following is the CNM1ROP help panel: /*DESCRIPTION: Prompt for OS/2 command to be sent to SPCF processor * *** +CNM1ROP %Send OS/2 command to OS/2 Remote Operations Service + $ +Current Service Point:&DSP +Current Application:&DA $ $You can send an OS/2 command to Remote Operations Service in a NetView $service point for execution. The output from the command to the standard out- $put device will be routed back to your NetView operator console. $ $ \Examples:$ $ $ %ROP DIR C:"\*.CMD $- List CMD files in PC root directory. $ $ %ROP TYPE C:"\CONFIG.SYS $- Type contents of CONFIG.SYS on your NetView $ terminal. $ $Note: Do not send to ROP Service OS/2 commands that require input from the $PC keyboard since this blocks the OS/2 session. $(You may however provide such keyboard input in advance through OS/2 piping.) $ $ Ы %===>°&PROMPT $ $ PF2= End PF3= Return PF6= Roll PF7= Back PF8= More PF11= Entry Point ═══ 6. Developing OS/2 Programs to Interact with SPA Router ═══ Developing OS/2 Programs to Interact with SPA Router The API for SPA Router allows other applications to interact with SPA Router and communicate with the NetView program. The function calls supported by the SPA Router API can be divided into the following two types: o Those provided for Service Point Command Facility (SPCF) functions (referred to in the remainder of this book as SPCF function calls and collectively as the SPCF API). These SPCF function calls enable an OS/2 program to communicate with the NetView program through SPA Router. These are documented in SPCF Function Calls. o The function calls to SPA Router for configuration and management. These are described in this appendix. The SPA Router API uses a dynamically linked library to access information from the executing SPA Router. Users are supplied with a header file (RTRC.H) and library to be linked with (RTRAPI.LIB) to access any of the API. The following files are supplied: DCJVC00.DLL Contains all the dynamic link library (DLL) API for SPCF and the new API function calls added by SPA Router for management (for example, RTRApplEnum()). RTRAPI.LIB The import library used by users to access all the function calls of SPA Router. RTRC.H C language header file containing API prototypes and data structure definitions to access all SPA Router function calls. ═══ 6.1. SPA Router API Support of DBCS ═══ The SPA Router API supports double-byte character set (DBCS). For all of the function calls of the SPA Router API, any multiple-character field can contain either single-byte character set (SBCS) characters only or DBCS characters only or a mix of the two types of characters. This is true for both input fields received from callers and fields returned by SPA Router. For example, the target application name, the NetView operator name, the command received from the NetView program, and the reply that SPA Router sends to the NetView program are fields that support DBCS or a mix of DBCS and SBCS. However, the length of the fields is the same whether SBCS characters, DBCS characters, or a mix of the two characters are used. For example, if a field is defined to contain 8 characters and only DBCS characters are being used for that field, the field can contain only 4 DBCS characters. For all text or strings sent to SPA Router or received from SPA Router, the length is in bytes, not in characters. For example, if a caller is sending a reply text containing 10 SBCS characters and 6 DBCS characters, the length field passed to SPA Router must indicate that the reply text is 22 bytes (10 + (6*2)) long. All data structures used to call SPA Router function calls are the same in the DBCS environment as in the SBCS environment. DBCS affects the data translation between workstation code pages and NetView EBCDIC code pages because DBCS is implemented differently in those two environments. Specifically, DBCS EBCDIC inserts a single byte shift-out character (SO), which is (Ox0E), in the data stream to signal the beginning of DBCS characters; to signal the end of DBCS characters, DBCS EBCDIC inserts a single byte of shift-in (to SBCS) character (SI), which is (0x0F). DBCS workstation code pages do not need any such character insertions to identify the boundaries of SBCS and DBCS data. Due to the insertions of SO and SI characters, workstation code page data containing DBCS characters is longer after being translated to DBCS EBCDIC. Similarly, DBCS text received from the NetView program is shorter after being translated to the DBCS workstation code page due to the deletions of the SO and SI characters. Function calls can request that SPA Router do the data translation or the application can do the data translation. If the application is doing the translation, the DBCS issues need to be handled by the application. For function calls that request that SPA Router do the data translation, SPA Router handles the data translation in the following way. When a command received from the NetView program is parsed by SPA Router, the length of the command returned to the caller is the byte length of the command according to the workstation code page (without the SO and SI characters). For reply messages being sent to the NetView program, no problems are encountered as long as each message when translated to EBCDIC is less than or equal to 253 bytes. For translated messages that are larger than 253 bytes, SPA Router breaks the message into two messages. The first message contains as much of the original message as possible, up to 253 bytes and without breaking any SO-SI pairing. The remaining data goes into the second message. ═══ 6.2. API Function Calls ═══ The following function calls are included in this section: RTRApplEnum RTRApplGetInfo RTRApplDel RTRConfigGetInfo RTRConfigSetInfo RTRShutdown RTRStart This section: contains a description of each SPA Router configuration and management function call. The following information is included for each function call: o Syntax o Return codes o Remarks o Example ═══ 6.3. RTRApplEnum ═══ RTRApplEnum The RTRApplEnum function returns information about all of the applications presently registered with SPA Router. Format #include <rtrc.h> unsigned far pascal RTRApplEnum(level, buf, buflen, entriesread, totalentries); unsigned short level; unsigned char far * buf; unsigned short buflen; unsigned short far * entriesread; unsigned short far * totalentries; Example Return Codes ═══ <hidden> level ═══ Specifies the level of detail (0,1) returned in the appl_info data structure within the buf memory space. Example ═══ <hidden> buf ═══ Points to a memory space, which was allocated by an application, where the information about all application names registered with SPA Router is returned. The first part of this buffer should allow for 16 bytes of reserved space, and the remaining bytes are used for a series of the appl_info data structure. There is a #define, which is named RTR_API_RESERVED, in the RTRC.H file. This #define has a value of 16 bytes. API users can set any value for these 16 bytes of reserved space (that is, no initializing needs to be done). SPA Router uses this reserved space in remote procedure call (RPC) and avoids extra byte copying. ═══ <hidden> buflen ═══ Specifies the size (in bytes) of the buf memory area. ═══ <hidden> entriesread ═══ Points to an unsigned short integer indicating the number of entries that were returned in buf. ═══ <hidden> totalentries ═══ Points to an unsigned short integer indicating the number of entries that were available. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_NOT_STARTED │ 14 │ SPA Router was not started. It can be started by calling │ │ │ │ RTRStart(). │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_LEVEL │ 31 │ The LEVEL parameter is invalid. LEVEL can be 0 or 1 │ │ │ │ only. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MEM_ACCESS │ 32 │ The buffer buf passed does not have the length buflen │ │ │ │ specified. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MORE_DATA │ 33 │ Additional data is available, but the buffer is too │ │ │ │ small. However, the passed buffer has been filled with as │ │ │ │ much data as there was room for. Issue the function call │ │ │ │ again using a larger buffer size. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BUF_TOO_SMALL │ 35 │ Buffer buf passed does not have the minimum reserved │ │ │ │ space of 16 bytes. The buffer passed must be at least 16 │ │ │ │ bytes long. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Examples ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ /* data structure for application enumerate buffer */ typedef struct _enumbuf { BYTE reserved [ RTR_API_RESERVED ] ; // reserved space for enum call appl_info_1 appinfo1 [ 128 ] ; // we declare space for the maximum of 128 // applications allowed for SPA Router } enumbuf ; enumbuf enumbuf1 ; main () { USHORT rc ; appl_info_1 *pappinfo1 ; /* this to point to every enumerated entry */ USHORT uentriesread, utotalentries ; rc = RTRApplEnum ( 1, // level 1 info desired (BYTE far *) &enumbuf1, /* buffer to fill enumerated info with */ sizeof ( enumbuf1 ) , // byte size of buffer space &uentriesread, &utotalentries ) ; if ( rc != RERR_SUCCESS ) printf("RTRApplEnum error, return code=%u\n", rc ) ; else { /* Show the Enumerate info obtained about all application */ printf("Router has %u applications registered, %u are listed below:\n", utotalentries, uentriesread ) ; pappinfo1 = &enumbuf1.appinfo1[0] ; // point to first applic entry while ( uentriesread-- ) { printf ( "%- 8s %u % 2u % 2u ", pappinfo1->appl_name, pappinfo1->cmds_waiting, pappinfo1->cmds_in_progress, pappinfo1->recv_q_depth ) ; /* format time in hh:mm:ss format and date in mm/dd/yy form */ printf( "%02d:%02d:%02d %02d/%02d/%02d\n", (USHORT) pappinfo1->hours, (USHORT) pappinfo1->minute, (USHORT) pappinfo1->seconds, (USHORT) pappinfo1->month, (USHORT) pappinfo1->day, pappinfo1->year % 100 ); pappinfo1++ ; // point to next entry of application information } // end of while loop } // if enumerate was successful } ═══ 6.4. RTRApplGetInfo ═══ RTRApplGetInfo The RTRApplGetInfo function retrieves information about a particular application. Format #include <rtrc.h> unsigned far pascal RTRApplGetInfo(applname, level, buf, buflen); unsigned char * applname; unsigned short level; unsigned char far * buf; unsigned short buflen; Example Return Codes ═══ <hidden> applname ═══ Points to an 8-character string containing the name of the application about which information is being requested. This application name must be entered in exactly the same way it was registered with SPA Router (at OPEN SPCF API call). In other words, no case translation or blank filling for names shorter than 8 characters is done. ═══ <hidden> level ═══ Specifies the level of detail (0,1) returned in the appl_info data structure. ═══ <hidden> buf ═══ Points to an appl_info_0 data structure if detail level 0 information is specified or it points to an appl_info_1 data structure if detail level 1 information is specified. Example ═══ <hidden> buflen ═══ Specifies the size (in bytes) of the buf memory area. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_NOT_STARTED │ 14 │ SPA Router was not started. It can be started by calling │ │ │ │ RTRStart(). │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_LEVEL │ 31 │ The LEVEL parameter is invalid. LEVEL can be 0 or 1 only. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MEM_ACCESS │ 32 │ The buffer buf passed does not have the length buflen │ │ │ │ specified. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BUF_TOO_SMALL │ 35 │ The passed buffer is to small to execute this API. It │ │ │ │ must be at least the size of the structure appl_info_0 │ │ │ │ for level 0 or appl_info_1 for level 1. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_NAME_UNKNOWN │ 15 │ The application name passed is not registered with SPA │ │ │ │ Router. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ CHAR applname[] = "TESTAPPL" ; /* initialize application name */ main () { USHORT rc ; appl_info_1 appinfo1 ; rc = RTRApplGetInfo ( applname, // application name to get info of 1 , // level 1 info wanted &appinfo1, sizeof ( appl_info_1 ) ) ; if ( rc != RERR_SUCCESS ) printf("RTRApplGetInfo error, return code=%u\n", rc ) ; else { /* Show the info obtained about application */ printf("\nApplication name : %s\n", appinfo1.appl_name ) ; printf("Receive queue depth : %u\n", appinfo1.recv_q_depth ); printf("Number of commands waiting : %u\n", appinfo1.cmds_waiting); printf("Number of commands being processed : %u\n", appinfo1.cmds_in_progress ); /* format time in hh:mm:ss format and date in mm/dd/yy form */ printf("Time of registration : %02d:%02d:%02d %02d/%02d/%02d\n", (USHORT) appinfo1.hours, (USHORT) appinfo1.minute, (USHORT) appinfo1.seconds, (USHORT) appinfo1.month, (USHORT) appinfo1.day, appinfo1.year % 100 ); } } ═══ 6.5. RTRApplDel ═══ RTRApplDel The RTRApplDel function deletes the application with the specified name from SPA Router. Format #include <rtrc.h> unsigned far pascal RTRApplDel(applname) unsigned char far * applname; Example Return Codes Remarks ═══ <hidden> applname ═══ Points to an 8-character string containing the application name that is to be deleted from SPA Router. This application name must be entered in exactly the same way it was registered with SPA Router (at OPEN SPCF API call). In other words, no case translation or blank filling for names shorter than 8 characters is done. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_NOT_STARTED │ 14 │ SPA Router was not started. It can be started by calling │ │ │ │ RTRStart(). │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_NAME_UNKNOWN │ 15 │ The application name passed is not registered with SPA │ │ │ │ Router. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Remarks ═══ The RTRApplDel function deletes the specified application name from SPA Router. This has the same effect as if the application itself called SPCF CLOSE API with the force option. The result is that the application access to SPA Router is forcefully closed and the NetView program is notified of incompletion of the outstanding commands addressed to the application. ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ CHAR applname[] = "TESTAPPL" ; /* initialize application name */ main () { USHORT rc ; /* Delete the application */ rc = RTRApplDel( applname ) ; if ( rc == RERR_SUCCESS ) printf("RTRApplDel call successfully deleted %s\n", applname ) ; else printf("RTRApplDel error for name:%s, return code=%u\n", applname, rc ) ; } ═══ 6.6. RTRConfigGetInfo ═══ RTRConfigGetInfo The RTRConfigGetInfo function retrieves all configuration information for SPA Router. Format #include <rtrc.h> unsigned far pascal RTRConfigGetInfo( pconfig_struc ); config_info far * pconfig_struc ; Example Return Codes ═══ <hidden> pconfig_struc ═══ Points to a config_info data structure. Example ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_NOT_STARTED │ 14 │ SPA Router was not started. It can be started by calling │ │ │ │ RTRStart(). │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MEM_ACCESS │ 32 │ The pconfig_struc specified must be at least as large as │ │ │ │ the struct cfg_info. No data was returned in the buffer. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ main () { USHORT rc ; config_info config ; // Get SPA Router config settings rc = RTRConfigGetInfo( (config_info far *) &config ) ; if ( rc != RERR_SUCCESS ) { printf("SPA Router ConfigGetInfo error, return code=%u\n", rc ) ; } else { printf("SPA Router is currently configured as follows:\n" ) ; printf("Maximum application names : %u\n", config.maxregapp ) ; printf("Maximum queue depth : %u\n", config.maxqdepth ) ; printf("EBCDIC code page for Netview : %u\n", config.hostcodepage) ; printf("Presentation Manager user interface : %s\n", ( (config.options & O_PM_ENABLE) ? "ON" : "OFF" ) ) ; } } ═══ 6.7. RTRConfigSetInfo ═══ RTRConfigSetInfo The RTRConfigSetInfo function sets the operating parameters for SPA Router. Format #include <rtrc.h> unsigned far pascal RTRConfigSetInfo( pconfig_struc ); config_info far * pconfig_struc ; ═══ <hidden> pconfig_struc ═══ Points to a config_info data structure. Example ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_NOT_STARTED │ 14 │ SPA Router was not started. It can be started by calling │ │ │ │ RTRStart(). │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MEM_ACCESS │ 32 │ The pconfig_struc specified must be at least as large as │ │ │ │ the struct cfg_info. SPA Router configuration was not │ │ │ │ attempted. SPA Router remains in its current state. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_MAXREGAPP │ 8 │ The maximum registered application parameter is not │ │ │ │ within the range acceptable. It can be between 1 and 128 │ │ │ │ inclusive. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_MAXQDEPTH │ 9 │ The maximum queue depth parameter is not within the range │ │ │ │ acceptable. It can be between 8 and 32 inclusive. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_HOSTCODEPAGE │ 10 │ The EBCDIC code page is either incorrect or not sup- │ │ │ │ ported. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_OS2CMMGR_NOT_LOADED │ 30 │ Communications Manager has not been started. Communi- │ │ │ │ cations Manager must be running before SPA Router can be │ │ │ │ started. Start Communications Manager before calling │ │ │ │ this function call again. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_TRACE │ 102 │ The trace status bits cannot be changed after trace is │ │ │ │ started. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ main () { USHORT rc ; config_info config ; config.maxregapp = 64 ; // applications maximum config.maxqdepth = 12 ; // receive queue depth system wide limit config.hostcodepage = 37 ; // EBCDIC code page for Host NetView config.options = O_PM_ENABLE ; // Allow Pres. Manager user interface to // be started. // Change the configuration of the already running SPA Router rc = RTRConfigSetInfo( (config_info far *) &config ) ; if ( rc == RERR_SUCCESS ) printf("SPA Router settings changed successfully\n") ; else printf("SPA Router ConfigSetInfo error, return code=%u\n", rc ) ; } ═══ 6.8. RTRShutdown ═══ RTRShutdown The RTRShutdown function performs the shutdown of SPA Router. Format #include <rtrc.h> unsigned far pascal RTRShutdown(); Example Return Codes ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_NOT_STARTED │ 14 │ SPA Router was not started. SPA Router shutdown is not │ │ │ │ needed. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ main () { USHORT rc ; rc = RTRShutdown() ; // stop the router if it is already running if ( rc == RERR_SUCCESS ) printf("SPA Router shutdown successfully\n") ; else printf("SPA Router shutdown error, return code=%u\n", rc ) ; } ═══ 6.9. RTRStart ═══ RTRStart The RTRStart function starts SPA Router with the specified configuration that was passed. A NULL pointer means to use the last saved settings of SPA Router. Format #include <rtrc.h> unsigned far pascal RTRStart( pconfig_struc ); config_info far * pconfig_struc ; Example Return Codes ═══ <hidden> pconfig_struc ═══ Points to a config_info data structure. It can be NULL to mean use the last configuration setup to start the router. Example ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_ALREADY_RUNNING │ 20 │ SPA Router is already running. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_EXECPGM_OF_ROUTER │ 37 │ SPA Router executable program could not be started (by │ │ │ │ OS/2 API call DOSEXECPGM()). Either the PATH environment │ │ │ │ variable no longer has ROP in its list or the executable │ │ │ │ file ROPROUT.EXE is missing from the directory where SPA │ │ │ │ Router and ROP Service were installed. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_STATUSPOST_OF_ROUTER│ 38 │ The SPA Router process failed to post the status (of │ │ │ │ success or failure) to this function call after it was │ │ │ │ started. This function call cannot determine whether SPA │ │ │ │ Router started successfully or not. To see if SPA Router │ │ │ │ started properly, call other function calls such as │ │ │ │ RTRAPPLENUM() or RTRCONFIGGETINFO(). This error condi- │ │ │ │ tion occurs if an OS/2 function call to a the named pipe │ │ │ │ \PIPE\ACS\SNA\NMVTSTAT returns an error when an attempt │ │ │ │ is made to collect the status from SPA Router after it │ │ │ │ has been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_RTR_API_ABORTED │ 36 │ An abort signal was received when more than one user │ │ │ │ tried to start SPA Router, and this user was waiting for │ │ │ │ start to complete and was interrupted by the abort │ │ │ │ action. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INIT_MEM_ALLOC │ 1 │ The SPA Router initialization failed due to memory allo- │ │ │ │ cation failure. SPA Router has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INIT_SHMEM_SPCIQ │ 3 │ The SPA Router initialization failed due to shared memory │ │ │ │ allocation failure for SPCI queue. SPA Router has not │ │ │ │ been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INIT_SPCIQ_CREATE │ 4 │ The SPA Router initialization failed because the SPCI │ │ │ │ queue to receive NMVT could not be created. SPA Router │ │ │ │ has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INIT_CP_XLATE │ 5 │ The SPA Router initialization failed because the EBCDIC │ │ │ │ to ASCII code page translation table setup failed. The │ │ │ │ wrong EBCDIC code page was specified. SPA Router has not │ │ │ │ been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INIT_APIPIPE_CREATE │ 21 │ The SPA Router initialization failed because the API │ │ │ │ support named pipe \PIPE\ACS\SNA\NMVTSPCI could not be │ │ │ │ created. SPA Router has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MEM_ACCESS │ 32 │ The pconfig_struc specified must be at least as large as │ │ │ │ the struct cfg_info. The SPA Router configuration was │ │ │ │ not attempted. SPA Router remains in its current state. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_MAXREGAPP │ 8 │ The maximum registered application parameter is not │ │ │ │ within the range acceptable. It can be between 1 and 128 │ │ │ │ inclusive. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_MAXQDEPTH │ 9 │ The maximum queue depth parameter is not within the range │ │ │ │ acceptable. It can be between 8 and 32 inclusive. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_HOSTCODEPAGE │ 10 │ The EBCDIC code page is either incorrect or not sup- │ │ │ │ ported. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_OS2CMMGR_NOT_LOADED │ 30 │ Communications Manager has not been started. Communi- │ │ │ │ cations Manager must be running before SPA Router can be │ │ │ │ started. Start Communications Manager before calling │ │ │ │ this function call again. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MAKENMPIPE_NMVTSTAT │ 100 │ The named pipe \PIPE\ACS\SNA\NMVTSTAT could not be │ │ │ │ created. This named pipe is used by SPA Router to post │ │ │ │ its status to the RTRStart function call. SPA Router has │ │ │ │ not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_DBCS_ACCESS │ 101 │ The DBCS OS/2 TRNSCALL.DLL file could not be loaded or │ │ │ │ the TRNSDT API entry point within TRNSCALL.DLL was not │ │ │ │ found. SPA Router has not been started. │ │ │ │ │ │ │ │ NOTE: This error occurs only when SPA Router is run in │ │ │ │ the DBCS OS/2 environment. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> #include <stdio.h> #include <rtrc.h> /* header file to access SPA Router APIs */ main () { USHORT rc ; config_info config ; rc = RTRStart( NULL ) ; // attempt to start router with default setup if ( rc == RERR_SUCCESS ) printf("SPA Router started successfully\n") ; else printf("SPA Router start error, return code=%u\n", rc ) ; /* Here we start the Router with configuration settings of our choice. */ RTRShutdown() ; // stop the router if it is already running config.maxregapp = 64 ; // applications maximum config.maxqdepth = 16 ; // receive queue depth limit config.hostcodepage = 37 ; // EBCDIC code page for Host NetView config.options = O_PM_ENABLE ; // Allow Pres. Manager Interface // start router with our settings rc = RTRStart( (config_info far *) &config ) ; if ( rc == RERR_SUCCESS ) printf("SPA Router started successfully with new settings\n") ; else printf("SPA Router start error, return code=%u\n", rc ) ; } ═══ 6.10. API Data Structures ═══ The C language header file RTRC.H is supplied to users to access the API of SPA Router. It contains the following definitions and data structures: /* Assign each SPCF API request code a symbolic name */ #define SPCF_OPEN 0x0301 // Open an applic name in SPA Router #define SPCF_OPENQDEPTH 0x0311 // Open a name with Q depth in SPA Router #define SPCF_CLOSE 0x0304 // Close applic resource in SPA Router #define SPCF_SENDRUNR 0x0302 // Send a Run Command Response #define SPCF_SENDCMDR 0x030B // Send a Command Response #define SPCF_SENDMSGU 0x030A // Send a Message Unsolicited #define SPCF_SENDNMVTU 0x030D // Send a preformatted NMVT Unsolicited #define SPCF_SENDERR 0x030C // Send an Error Sense to the host #define SPCF_RECVRUNC 0x0303 // Receive a Run Command Request #define SPCF_RECVACMD 0x0309 // Receive a Command Request /********************************************************/ /* Structure definition for ROPS SPA Router SPCF ARB */ /********************************************************/ struct spcf_arb { /*******************************/ char arbid[4] ; /* SPCF ARB ID 'ARB3' */ /* */ unsigned short reqcode ; /* SPCF request code */ /* */ unsigned char arblength ; /* Length of the SPCF ARB (96) */ /* */ unsigned char nmvt_key ; /* This field will contain the */ /* NMVT Key from of the NMVT */ /* received by a successful */ /* attempt to receive an */ /* unparsed NMVT. */ /* */ unsigned char reserve1 ; /* reserved byte */ /* */ unsigned short ret_code ; /* SPCF primary Return Code */ unsigned short ret_class ; /* SPCF primary Error Class */ unsigned short ret_type ; /* SPCF primary Error Type */ /* */ char applname[8] ; /* Name by which the */ /* application will be known */ /* to NetView host. If a name */ /* shorter than 8 chars is */ /* used, the name should be */ /* right justified in the */ /* field and the remainder */ /* of the field should be */ /* filled with blanks. */ /* */ char msgtype ; /* When sending a reply to a */ /* runcmd or sending a msg to */ /* the operator, the source of */ /* the reply. */ /* 'F' if from a file. */ /* 'B' if from a buffer. */ /* */ char msgfile [4] ; /* Four character name of a */ /* message file in the current */ /* directory whose extension */ /* is ".msg". Used only on */ /* runcmd replies or */ /* unsolicited msg to operator */ /* when msgtype is 'F'. */ /* */ char msgnum [4] ; /* Four character msg number */ /* with leading zeroes of the */ /* message to be sent to the */ /* host from the msgfile */ /* specified. Used only on */ /* runcmd replies or */ /* unsolicited msg to operator */ /* when msgtype is 'F'. */ /* */ unsigned short mblength ; /* Length of the unconverted */ /* message buffer being sent */ /* to the host. Used only on */ /* runcmd replies when msgtype */ /* is 'B' and convert is 'N'. */ /* */ unsigned short msgcount ; /* Number of messages to be */ /* converted being sent in the */ /* reply buffer. Used only on */ /* runcmd replies or */ /* unsolicited msg to operator */ /* when msgtype is 'B'. Must */ /* be 1 if convert is 'N'. */ /* */ char convert ; /* Indicates whether contents */ /* of reply buffer should be */ /* converted from ASCII to */ /* EBCDIC. Used only on runcmd */ /* replies when msgtype is 'B'.*/ /* */ unsigned char far *pmsgbuff ; /* Pointer to reply buffer. */ /* Used only on runcmd replies */ /* or unsolicited msg to oper */ /* when msgtype is 'B'. This */ /* buffer must have been */ /* dynamically allocated as */ /* shareable. */ /* */ unsigned char cmdlength ; /* Length returned of the */ /* runcmd received by a */ /* successful receive runcmd */ /* request. */ /* */ unsigned char far *pcommand ; /* Pointer returned by the API */ /* to the buffer containing */ /* the runcmd or unparsed */ /* command received by a */ /* receive request. */ /* */ unsigned char recvcorr[10]; /* Ten byte value returned */ /* that identifies a given */ /* command received from the */ /* host. */ /* */ unsigned char sendcorr[10]; /* Ten byte value used by the */ /* host to correlate a reply */ /* with a previously received */ /* runcmd or unparsed command. */ /* This value should be set to */ /* the recvcorr of the runcmd */ /* or unparsed command to */ /* which the program is */ /* replying. */ /* */ char forceclose ; /* Used only on close requests.*/ /* 'Y' indicates queued msgs */ /* and commands are to be */ /* the discarded and the API/CS*/ /* should send error sense */ /* data to the NetView host. */ /* 'N' will only close the */ /* interface if there are no */ /* queued messages or commands,*/ /* otherwise the API/CS will */ /* return an error return code */ /* to indicate that the close */ /* request failed. */ /* */ char opername[8]; /* An 8 char name of the */ /* NetView host operator who */ /* will receive the unsolicited*/ /* msg to the operator. Used */ /* only on send unsol msg to */ /* oper requests. If a name */ /* shorter than 8 chars is */ /* used, the name should be */ /* right justified in the field*/ /* and the remainder of the */ /* field should be filled with */ /* blanks. */ /* */ unsigned short putreplylen; /* The length of an unformatted*/ /* NMVT that is being sent to */ /* the host by a send */ /* unformatted NMVT request. */ /* */ unsigned char far *putreplybuf; /* A pointer to the buffer */ /* containing the unformatted */ /* NMVT to be sent to the */ /* NetView host. The buffer */ /* must have been previously */ /* allocated as shareable. */ /* */ unsigned char sensetype ; /* The sense code that will */ /* be sent to the NetView host */ /* by a Send Error Sense */ /* request. */ /* */ unsigned char lccstat ; /* The secondary sense code */ /* that will be sent to the */ /* NetView host by a Send Error*/ /* Sense request. This field */ /* is optional and must be set */ /* to zero if not used. */ /* */ unsigned char errordetail ; /* The error detail that */ /* will be sent to the */ /* NetView host by a Send Error*/ /* Sense request. This field */ /* is optional and must be set */ /* to zero if not used. */ /* */ unsigned char usersense[4] ; /* A four byte binary user */ /* sense code. Used on Send */ /* Error Sense requests only */ /* when sensetype is zero. */ /* */ unsigned char svkey ; /* The subvector in which the */ /* error was found. Used for */ /* Send Error Sense requests */ /* only. Field is optional */ /* and must be set to zero if */ /* not used. */ /* */ unsigned char sfkey ; /* The subfield in which the */ /* error was found. Used for */ /* Send Error Sense requests */ /* only. Field is optional */ /* and must be set to zero if */ /* not used. */ /* */ unsigned char qdepth ; /* The number of buffer */ /* entries to be reserved */ /* for the receive buffer of */ /* the target appl name */ /* opened. Used only with */ /* request code 0x311. This is */ /* the number of commands that */ /* can be sent from the host */ /* without the NetView/PC */ /* application receiving any */ /* commands. */ /* */ unsigned char reserve2 ; /* reserved byte */ /* */ unsigned long qhsema ; /* A ram semaphore handle that */ /* is returned on open calls */ /* and is cleared whenever */ /* there is a command in the */ /* receive buffer for the */ /* target appl name. */ /*******************************/ }; /* End of SPCF ARB definition */ #define APPNAMELEN 8 // eight character name length of applic #define RTR_API_RESERVED 16 // must be updated with size of (NEWARB) // return codes from APIs for users #define RERR_SUCCESS 0 #define RERR_INIT_MEM_ALLOC 1 /* Memory Allocation Error at Router Initialization. Router could not be started. */ #define RERR_INIT_SHMEM_ALLOC 2 /* Shared memory Creation Error at Router Initializing. Router could not be started. */ #define RERR_INIT_SHMEM_SPCIQ 3 /* Shared Memory Creation Error for SPCI Queue at Router Initializing. Router could not be started. */ #define RERR_INIT_SPCIQ_CREATE 4 /* SPCI Queue "\QUEUES\ACS\SNA\NMVTSPCI" could not be created. Router could not be started. */ #define RERR_INIT_CP_XLATE 5 /* EBCDIC-ASCII code page translation table setup failed at Router initialization time. Router could not be started. */ #define RERR_BAD_MAXREGAPP 8 /* MAXREGAPP parameter is not within the range acceptable. */ #define RERR_BAD_MAXQDEPTH 9 /* MAXQDEPTH parameter is not within the range acceptable. */ #define RERR_BAD_HOSTCODEPAGE 10 /* HOSTCODEPAGE number is not a supported EBCDIC code page. */ #define RERR_BAD_PMFLAG 11 /* PM flag is incorrectly specified. It can be only "ON" or "OFF". */ #define RERR_BAD_PRI_CLASS 12 /* Router process priority class specified via "PRI_CLASS" parameter is not an acceptable one. */ #define RERR_BAD_PRI_LEVEL 13 /* Router process priority value specified via "PRI_LEVEL" parameter is not within the acceptable range. */ #define RERR_RTR_NOT_STARTED 14 /* The Service Point Application Router has not been started. So API called failed. */ #define RERR_NAME_UNKNOWN 15 /* Application name specified is not registered with the router. Operation requested failed. */ #define RERR_NAME_INVALID 16 /* Application name has incorrect length or format. Operation requested failed. */ #define RERR_RTR_ALREADY_RUNNING 20 /* The Router is already running. */ #define RERR_INIT_APIPIPE_CREATE 21 /* Router API support named "\PIPE\ROP\APIPIPE" could not be created . Router could not be started. */ #define RERR_OS2CMMGR_NOT_LOADED 30 /* OS/2 Communication Manager has not been started. You must start OS/2 Comm Mgr before starting the Service Point Application Router. */ #define APIONLY_ERROR_CODE 31 /* starts where CLUI codes ends */ #define RERR_INVALID_LEVEL ( APIONLY_ERROR_CODE ) #define RERR_MEM_ACCESS ( APIONLY_ERROR_CODE + 1 ) #define RERR_MORE_DATA ( APIONLY_ERROR_CODE + 2 ) #define RERR_NOT_ENOUGH_DATA ( APIONLY_ERROR_CODE + 3 ) #define RERR_BUF_TOO_SMALL ( APIONLY_ERROR_CODE + 4 ) #define RERR_RTR_API_ABORTED ( APIONLY_ERROR_CODE + 5 ) #define RERR_EXECPGM_OF_ROUTER ( APIONLY_ERROR_CODE + 6 ) #define RERR_STATUSPOST_OF_ROUTER ( APIONLY_ERROR_CODE + 7 ) #define RERR_ERROR_OPENING_INI_FILE 40 /* Config Profile ini file RTR.INI for SPA Router could not be open. */ #define RERR_MAKENMPIPE_NMVTSTAT 100 /* could not make named pipe \PIPE\ACS\SNA\NMVTSTAT used to collect status from SPA Router process. */ #define RERR_DBCS_ACCESS 101 /* DBCS OS/2 TRNSCALL.DLL could not be loaded or TRNSDT API entry point within TRNSCALL.DLL not found. SPA Router not started. This error occurs only when SPA Router is run in DBCS OS/2 environment. */ #define RERR_TRACE 102 /* Trace status bits cannot be changed when trace is started. */ #define RERR_UNKNOWN_API 999 /* The SPA Router received an unknown API request to be executed. */ // Application Information (Level 0) // typedef struct _appl_info_0 { unsigned char appl_name [ APPNAMELEN+1 ] ; } appl_info_0 ; // // appl_name : is an ASCIIZ string containing the name of a registered // application. // // Application Information (Level 1) // typedef struct _appl_info_1 { unsigned char appl_name [ APPNAMELEN+1 ] ; unsigned long time ; unsigned short cmds_waiting; unsigned short cmds_in_progress; unsigned short recv_q_depth; unsigned char hours; unsigned char minute; unsigned char seconds; unsigned char day; unsigned char month; unsigned short year; /* in XXXX like 1990 form */ } appl_info_1 ; // // appl_name : is an ASCIIZ string containing the name of a registered // application. // // time : specifies the time of the registered application represented // as seconds from 1/1/1970. It is used to simplify the sorting // of applications by time. // // cmds_waiting: specifies the number of commands waiting in the // receive queue of the router for this application. // // cmds_in_progress: specifies the number of commands being // processed by the application whose responses have not // been sent out yet. // // recv_q_depth: specifies the depth of the receive queue that the // application chose ( or picked up as default ) when it opened // access to the router. // // The following fields give the time and date of application registration // ( OPEN API ) to the router. It is passed in exactly the same form that // OS/2 DosGetInfoSeg() API call returns these information // // hours: The hour the application name was registered with the router. // A value from 0 to 24. // minute: The minute the application name was registered with the router. // A value from 0 to 59. // seconds: the seconds the application name was registered with the router. // A value from 0 to 59. // day: the day the application name was registered with the router. // A value from 1 to 31. // month: the month the application name was registered with the router. // A value from 1 to 12. // year: the year the application name was registered with the router. // A value from 1970 to XXXX. For example, for the year 1990, it // will be 1990. // Configuration information // typedef struct _cfg_info { unsigned short maxregapp; unsigned short maxqdepth; unsigned short hostcodepage; unsigned short options; unsigned short priorityclass; // Not used in release 1.0 unsigned short prioritylevel; // Not used in release 1.0 } config_info ; // // maxregapp: // specifies the maximum number of applications that // may be registered with the router and run concurrently. // maxqdepth: // specifies the maximum receive queue depth for any application. // hostcodepage: // specifies the EBCDIC code page number used to // translate text information to and from the Host. // options: // specifies the various configuration options. The options are defined // as follows ( bits are numbered with 0 being the least significant one). // Option Flag Bit Number Meaning // ---------------------------------------------------------- // O_PM_ENABLE 0 If set, enables the PM full screen user // interface of the router. Otherwise PM // interface is disabled. // O_TRACEAPI 1 If set, enables all API traces for SPA // Router. If not set, API traces for SPA // Router is disabled. // O_TRACEDATA 2 If set, enables all NMVT reception and // transmission traces to and from SPA // Router. If not set, NMVT traces for SPA // Router is disabled. // // RESERVED 3-15 All other bits are reserved for future use // and should be set to 0. // priorityclass: // Not used in this release. The OS/2 process priority class of the SPA // Router process. This field is now ignored but for future release // compatibility we suggest you put 0xFFFF here. // prioritylevel // Not used in this release. The OS/2 process priority value of the SPA // Router process. This field is now ignored but for future release // compatibility we suggest you put 0xFFFF here. #define O_PM_ENABLE 0x01 // bit mask for PM UI enable/disable #define O_TRACEAPI 0x02 // bit mask for Trace API enable/disable #define O_TRACEDATA 0x04 // bit mask for Trace DATA enable/disable // API declaration for all SPA Router APIs short far pascal DCJVC0C ( struct spcf_arb far * ) ; unsigned short far pascal RTRApplEnum ( unsigned short , unsigned char far * , unsigned short , unsigned short far * , unsigned short far * ) ; unsigned short far pascal RTRApplGetInfo ( unsigned char far *, unsigned short, unsigned char far *, unsigned short ); unsigned short far pascal RTRApplDel ( unsigned char far * ) ; unsigned short far pascal RTRConfigGetInfo ( config_info far * ) ; unsigned short far pascal RTRConfigSetInfo ( config_info far * ) ; unsigned short far pascal RTRStart ( config_info far * ) ; unsigned short far pascal RTRShutdown ( void ) ; ═══ 7. SPCF Function Calls ═══ Service Point Command Facility Function Calls This section discusses the Service Point Command Facility (SPCF) function calls of the SPA Router API. SPA Router supports a 67-byte application request block (ARB) and a 90-byte ARB. The topics included in this section are: Sample Programs Illustrating SPCF Function Calls Opening Application Names Commands and Request Codes Supported Function Calls SPCF ARB SPCF API Return Codes (DCJVC0C Return Codes) Error Conditions Not Reported in ARB Return Codes NetView Commands Supported by SPA Router ═══ 7.1. Sample Programs Illustrating SPCF Function Calls ═══ Two sample programs that are written in C language are provided to show how the SPCF function calls can be used to interact with the NetView program. These sample programs are shipped with the IBM Communications Manager/2 Version 1.1 Application Programming Guide on the Communications Manager/2 API Support Diskette. The first sample program is SMPECHO.C. It echoes every RUNCMD that the NetView program sends to an application. It illustrates the use of the following SPCF function calls: o Open SPCF API o Receive a RUNCMD message o Send a RUNCMD response The second program is SMPSPCF.C. It illustrates the use of all of the SPCF function calls. It is a simple menu-driven program that allows the user to invoke any SPCF function call with parameters specified by the user. To compile and make the two sample programs, use the SAMPLE.MAK file included with the programs. The source code of the sample programs provides additional information about the programs. ═══ 7.2. Opening Application Names ═══ Up to 128 application names can be opened with the SPA Router to receive commands from the NetView program. It is necessary to fill in the target application name when making any SPCF request for distinct target application names. Any application can open as many names as it needs; however, consideration must be given to the fact that a 128-name limit is imposed system wide and any name slot used by an application reduces the available names in the system. Most application programs probably will not require more than one target application name be open at one time. There are two advantages to opening multiple target application names for an application. The first advantage is an increase in the number of commands that can be queued from the host (this can also be accomplished by specifying the queue depth with the 0311H request code). The second advantage is an increase in the number of commands that can be received by the application program without replying to them (this number is fixed at eight per target application name). Each target application name should be closed prior to application termination. Any target application names left open at program termination are forced closed by the SPCF API, all outstanding commands and commands not yet received for that target application name are flushed, and error sense data is sent to the host. In addition, it is required that the buffers pointed to by the MSGBUFF and PUTREPLY fields of the ARB be buffers that are dynamically allocated as shareable memory using DosAllocSeg when making SPCF requests that use these fields. This is so that OS/2 function calls DosGiveSeg or DosGetSeg can be called with these buffers. When an application opens a name without setting a receive queue depth (request code 0301H), eight commands can be sent from the NetView program without being received by the target application. The receive queue depth can be changed at open time to a value from 1 through 32 as specified by the application program when it uses the 0311H request code to open the target application name. However, the receive queue depth cannot be larger than the maximum queue depth defined for the configuration. The number of data service request blocks (DSRBs) on the NetView host must be greater than or equal to the receive queue depth of an application in order to queue the maximum number of commands. Each receive buffer passed to an application when it issues any receive function call is distinct. The receive buffers for a given target application name remain intact until the command is answered successfully or the target application name is closed. Application programs should not indiscriminately open large numbers of target application names or specify large queue depths without a need to do so. Such actions consume significant quantities of memory. ═══ 7.3. Commands and Request Codes Supported ═══ The SPCF API provides the capability for OS/2 application programs to: o Receive any unparsed command from the NetView program and respond to the command o Send preformatted unsolicited messages to a NetView operator o Receive a RUNCMD message from a NetView operator and respond to the message Only RUNCMD requests from the NetView program are parsed by the SPCF API. All other requests (LINKDATA, LINKPD and LINKTEST) coming from the NetView program must be received by the application by an unparsed receive function call of SPCF. The application then must parse this NMVT, interpret the meaning of the command, and create the reply NMVT to send to the NetView program. SPA Router does not provide SPCF NMVT Build and Parse function calls. The SPCF API also provides for the transportation of messages from and replies to a user-supplied data services task (DST) invoked from an operator services task (OST) running under the NetView program on the host. The request codes used by the SPCF API and descriptions are: 0301H Open a specified target application name. 0311H Open a specified target application name and define the depth of the receive queue for that target application name. 0302H Send a RUNCMD response. 0303H Receive a RUNCMD message. 0304H Close the SPCF API. 0309H Receive a command. An unparsed command NMVT, if there is one, is returned. The application is required to parse the NMVT to determine the command. 030AH Send a message. An unsolicited message is sent to a NetView operator from a file or from a buffer. 030BH Send a command response. The response NMVT is sent to the NetView program as received from the application. The application is required to format the NMVT. 030CH Send error sense. The application has the option of sending error sense data provided by SPA Router or sending user-defined error sense data. 030DH Send a preformatted unsolicited NMVT to the NetView program. ═══ 7.3.1. The Command Correlator ═══ When each command or message is received, a correlator is returned to the application in the RECVCORR field of the ARB. The correlator of the message must be stored in the SENDCORR field of the ARB when responses are sent. Up to eight commands can be received before the application must send a response. The application must save the correlator for each command and ensure that the correct correlator is used for the response. The application program using the SPCF API is responsible for ensuring that the response correlator (SENDCORR field in the ARB) matches the command that is being responded to and for ensuring that the response data text is correct. ═══ 7.3.2. The Response Message ═══ RUNCMD response messages may be contained in message files or may be passed in a buffer from the OS/2 application to the SPCF API to be sent to the NetView program. If the response message is to be contained in a message file, the file name must be in the form cccc.MSG, where c represents any character that can be used in naming an OS/2 file. Message files can be created with most popular PC editors. A message must begin with the 4-character numeric message identifier terminated with a blank. The blank may be followed by up to 253 characters of text terminated by the string X'0D0A' (carriage return, line feed). The message file must be in the current directory of the application or in a directory that is listed in DPATH of the application environment. RUNCMD response messages from the application are passed to the SPCF API in a buffer or message file. The application specifies whether the message data is to be translated from ASCII to EBCDIC before it is sent. If translation is not requested, only one message of up to 32478 bytes can be sent. If translation is requested, several messages can be put in the one message buffer, which holds approximately 32KB. The translation performed uses the current code page of the application process (obtained when the application name was opened by the SPCF Open function call) as the source, and the target code page is the system-wide EBCDIC code page selected for SPA Router. Use the physical unit (PU) name for SPA Router as the service point name to send messages or commands to the target SPA Router. The applications using the SPCF function calls must first open a name with SPA Router that is known to programs and operators communicating with the applications. To send unsolicited messages to an operator, the application must know the operator's NetView logon name. ═══ 7.3.3. Receiving and Sending Commands and Messages ═══ To use the SPCF API to receive commands and messages from a NetView operator and send messages or respond to commands, code the application to perform the following steps and subroutine calls: 1. Construct an ARB with ARB LENGTH set to 96. 2. If using request code 0311H for the Open, set the QUEUE DEPTH field to the desired value (1-32), but not more than the maximum queue depth defined for the configuration. 3. Call DCJVC0C with request code 0301H or 0311H to open a target application name for use with the SPCF API and save the receive queue semaphore handle that was returned in the ARB. 4. Wait for the receive queue semaphore handle that was returned by the Open for the specified target application name to be cleared by making a call to DosSemWait or DosMuxSemWait. When the semaphore is cleared, this indicates that a command is available for the target application name with which the receive queue semaphore handle is associated. 5. Call DCJVC0C with the appropriate receive request code: o Receive a RUNCMD message (0303H) o Receive a command (0309H) 6. Store the correlator of the received command in the SENDCORR field of the ARB. 7. Call DCJVC0C with the appropriate request code to send a response: o Send a RUNCMD response message (0302H) o Send a command response (030BH) o Send error sense (030CH) 8. Call DCJVC0C with request code 0304H to close the application name. Note: If data is required to be sent to the host in a format not supported by the RUNCMD, an operator services task (OST) and data services task (DST) can be written and then installed on the NetView program to provide the unique support required. See the NetView publications for guidance about how to provide this support. Required resources must have been defined whether the RUNCMD is used or user-supplied command processors are used. ═══ 7.4. Function Calls ═══ The following function calls are described: Open SPCF API Open SPCF API and specify receive queue depth Receive a RUNCMD message Send a RUNCMD response Send a message Receive a command Send a command response Send error sense Send a preformatted unsolicited NMVT to NetView Close SPCF API The ARB definition for these function calls is described in SPCF ARB. ═══ 7.5. Open SPCF API ═══ Open SPCF API This function enables an application to use the SPCF functions of the SPA Router to communicate with the host as a specified target application name. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. Lengths of 90 or 67 can be used. 4. Store the target application name in the TARGET NAME field of the ARB. 5. Store 0301H in the REQUEST CODE field of the ARB. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'11' │ X'46' │ Application name already exists. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'0A' │ X'04' │ Maximum application names in the system already │ │ │ │ │ opened. No more names available. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'31' │ X'09' │ Dynamic memory not available in the system to satisfy │ │ │ │ │ the Open request. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.6. Open SPCF API and Specify Receive Queue Depth ═══ Open SPCF API and Specify Receive Queue Depth This function allows an application to use the SPCF functions of the SPA Router to communicate with the host as a specified target application name. In addition, this call allows the application to specify the depth of the receive queue for the target application name being opened. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. 4. Store the target application name in the TARGET NAME field of the ARB. 5. Store 0311H in the REQUEST CODE field of the ARB. 6. Store the desired receive queue depth (1-32) in the QUEUE DEPTH field of the ARB. The receive queue depth cannot be greater than the maximum queue depth defined for the configuration. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'11' │ X'46' │ Application name already exists. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'0A' │ X'04' │ Maximum application names in the system already │ │ │ │ │ opened. No more names available. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'1C' │ Queue depth requested is not within the acceptable │ │ │ │ │ range. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'31' │ X'09' │ Dynamic memory not available in the system to satisfy │ │ │ │ │ the Open request. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.7. Receive a RUNCMD Message ═══ Receive a RUNCMD Message This function receives a message from an operator or a CLIST or a REXX exec. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Wait on the receive queue semaphore handle associated with this target application name using the OS/2 function DosSemWait or DosMuxSemWait. When the semaphore clears, this indicates that there is a command in the receive queue of the associated target application name. 7. Store 0303H in the REQUEST CODE field of the ARB. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. Results Return code Error class Error type Cmdlgth Command Recvcorr Comments You must document for the NetView operator the format and content of RUNCMD messages received, and response messages sent. The SPA Router SPCF API and the NetView program provide only for the transportation of the messages. They do not define message content. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'02' │ X'00' │ X'00' │ Application name queue is currently empty. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'94' │ X'92' │ Maximum number of Gets (8) have been done. You need to │ │ │ │ │ respond to one or more outstanding Gets before new │ │ │ │ │ command request will be satisfied. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'02' │ X'01' │ X'1A' │ The application name queue became empty due to invalid │ │ │ │ │ run command received from the host for this name, so │ │ │ │ │ no command request is available. Distinguish this case │ │ │ │ │ with returned code of 02,00,00 for application name │ │ │ │ │ queue being empty when the call is processed. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'4C' │ X'62' │ The next command queued for the application is not a │ │ │ │ │ RUNCMD command, so it cannot be parsed for satisfying │ │ │ │ │ this verb. Use verb 0x0309 (Receive any command) to │ │ │ │ │ get this command and parse it. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.8. Send a RUNCMD Response ═══ Send a RUNCMD Response This function sends a response to a RUNCMD message. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Store 0302H in the REQUEST CODE field of the ARB. 7. If a message is to be sent from a message file, set up the following ARB fields: a. MSGTYPE to F (file) b. MSGFILE with the 4-character name of the message file that contains the message to be sent to the NetView program c. MSGNUM with the 4-character number of the message in the message file 8. If a message is to be sent from a message buffer and the message is to be translated, set the following ARB fields: a. MSGTYPE to B (buffer). b. MSGBUFF to the address of the message buffer. This address must be of the memory buffer containing the messages that was dynamically allocated by the application by using OS/2 DosAllocSeg function with the flags set for the function call such that the buffer is shareable by both DosGiveSeg and DosGetSeg. c. MSGCOUNT to the number of messages to be sent from the message buffer. d. CONVERT to Y. 9. If a message is to be sent from a message buffer and the message is not to be translated, set the following ARB fields: a. MSGTYPE to B (buffer). b. MSGBUFF to the address of the message buffer. This address must be of the memory buffer containing the messages that was dynamically allocated by the application by using OS/2 DosAllocSeg function with the flags set for the function call such that the buffer is shareable through both DosGiveSeg and DosGetSeg. c. MSGCOUNT to 1. d. MBLENGTH to the message length. e. CONVERT to N. 10. Store the Recvcorr correlator from the received RUNCMD in the SENDCORR field of the ARB. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. Comments To send unformatted data to the host, you must provide a NetView command processor that can handle the unformatted data major vector key (X'1309'). To send message IDs and replacement text to the NetView program, your application must build the NMVT including the X'0A' subvector. You must then send the RUNCMD response NMVT as described in Send a Command Response. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'2F' │ X'92' │ No Get is outstanding for this name, so cannot send │ │ │ │ │ response. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'17' │ X'01' │ The correlator given is incorrect. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'13' │ Invalid length received for reply message from buffer │ │ │ │ │ or file. Also, if the maximum I-field size is set to │ │ │ │ │ less than 512 and response results in NMVTs greater │ │ │ │ │ than 512 bytes, this error code is returned. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'62' │ X'60' │ Cannot talk to host. SSCP-PU session between Communi- │ │ │ │ │ cations Manager and host is not active. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'09' │ Shared memory passed cannot be accessed by the SPA │ │ │ │ │ Router process. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'48' │ Message type field contains a value other than X'B' or │ │ │ │ │ X'F'. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'48' │ Message not found. Message format may be incorrect. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'44' │ Message file not found or could not be opened for read │ │ │ │ │ access. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.8.1. RUNCMD Response Message Buffer ═══ The format of the message buffer pointed to by the MSGBUFF field of the ARB when CONVERT is Y and MSGTYPE is B is shown in Message Buffer Format when CONVERT Is Y. Several messages in the buffer may be sent. The application sets the MSGCOUNT field of the ARB to the number of messages in the message buffer to be sent. Each message is preceded by a 1-byte length field (L) that contains the length of the message. The length of each message must be equal to or less than 253 bytes. Message data must be in ASCII (uppercase, lowercase, or mixed-case letters can be used). No carriage return-line feed pair is required to terminate a message as is the case for messages-in-file (messages-in-file is not preceded by a message length, so they need message terminator marks of carriage return-line feed pair). The sum of all the lengths fields (for the number of messages to be sent as specified by the MSGCOUNT field of the ARB) must be equal to or less than 32478 minus 2 times the value of the MSGCOUNT field: L1 + L2 ... + Ln =< 32478 - (2 X MSGCOUNT) Where MSGCOUNT = n ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Message Buffer Format when CONVERT Is Y │ ├──────┬───────────────────────────────────────────────────────────────────────────────────────────┤ │ L1 │ Message data │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ L2 │ Message data │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ . │ . │ │ . │ . │ │ . │ . │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ Ln │ Message data │ └──────┴───────────────────────────────────────────────────────────────────────────────────────────┘ ═══ 7.9. Send a Message ═══ Send a Message This function sends an unsolicited message to a NetView operator from a file or from a buffer. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the LENGTH field of the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Store 030AH in the REQUEST CODE field of the ARB. 7. If a message is to be sent from a message file, set up the following ARB fields: a. MSGTYPE to F (file) b. MSGFILE with the 4-character name of the message file that contains the message to be sent to the NetView program. c. MSGNUM with the 4-character number of the message in the message file. 8. If a message is to be sent from a message buffer, set the following ARB fields: a. MSGTYPE to B (buffer). b. MSGBUFF to the address of the message buffer. This address must be of the memory buffer containing the messages that were dynamically allocated by the application using the OS/2 DosAllocSeg function with the flags set for the function call such that the buffer is shareable via both DosGiveSeg and DosGetSeg. c. MSGCOUNT to the number of messages to be sent from the message buffer. d. CONVERT to Y (yes). 9. Store the NetView operator's name in the OPERATOR NAME field of the ARB in ASCII. If the name contains all blanks, the name defaults to the designated NetView operator console. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. Comments The CONVERT field is ignored. All unsolicited messages to the host are converted. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'13' │ Invalid length received for reply message from buffer │ │ │ │ │ or file. Also, if the maximum I-field size is set to │ │ │ │ │ less than 512 and response results in NMVTs greater │ │ │ │ │ than 512 bytes, this error code is returned. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'62' │ X'60' │ Cannot talk to host. SSCP-PU session between Communi- │ │ │ │ │ cations Manager and host is not active. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'09' │ Shared memory passed cannot be accessed by the SPA │ │ │ │ │ Router process. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'48' │ Message type field contains a value other than X'B' or │ │ │ │ │ X'F'. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'48' │ Message not found. Message format may be incorrect. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'44' │ Message file not found or could not be opened for read │ │ │ │ │ access. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.10. Receive a Command ═══ Receive a Command This function receives an unparsed command NMVT. The application is required to parse the NMVT to determine the command. (The length is found in the first 2 bytes, in host format; that is, high byte, low byte.) Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Wait on the receive queue semaphore handle associated with this target application name using the OS/2 function DosSemWait or DosMuxSemWait. When the semaphore clears, it indicates that there is a command in the receive queue of the associated target application name. 7. Store 0309H in the REQUEST CODE field of the ARB. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. PARSE ID (7) Command (42) Recvcorr (46) ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'02' │ X'00' │ X'00' │ Application name queue is currently empty. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'94' │ X'92' │ Maximum number of Gets (8) have been done. You need to │ │ │ │ │ respond to one or more outstanding Gets before the new │ │ │ │ │ command request will be satisfied. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.11. Send a Command Response ═══ Send a Command Response This function sends a response to a command from the NetView program. The response NMVT is sent to the NetView program as received from the application. The application is required to format the NMVT. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Store 030BH in the REQUEST CODE field of the ARB. 7. Store the Recvcorr correlator from the received command in the SENDCORR field of the ARB. 8. Store the length of the response NMVT in the PUTREPLY LENGTH field of the ARB. 9. Store the address of the response NMVT in the PUTREPLY field of the ARB. This address must be of the memory buffer containing the response NMVT that was dynamically allocated by the application using the OS/2 DosAllocSeg function with the flags set for the function call such that the buffer is shareable through both DosGiveSeg and DosGetSeg. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'2F' │ X'92' │ No Get is outstanding for this name, so cannot send │ │ │ │ │ response. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'17' │ X'01' │ The correlator given is incorrect. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'13' │ Invalid length received for reply message from buffer │ │ │ │ │ or file. Also, if the maximum I-field size is set to │ │ │ │ │ less than 512 and response results in NMVTs greater │ │ │ │ │ than 512 bytes, this error code is returned. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'62' │ X'60' │ Cannot talk to host. SSCP-PU session between Communi- │ │ │ │ │ cations Manager and host is not active. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'09' │ Shared memory passed cannot be accessed by the SPA │ │ │ │ │ Router process. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.12. Send Error Sense Data ═══ Send Error Sense Data This function sends error sense data to the NetView program in response to a command. The sense data may be defined by the application. The X'7D' subvector is used. Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Store 030CH in the REQUEST CODE field of the ARB. 7. Store the Recvcorr correlator from the received command in the SENDCORR field of the ARB. 8. Store the appropriate values in the following ARB fields: SENSETYPE (see SENSETYPE Values, Data, and Descriptions) LCCSTAT (see Defined LCCSTAT Values) ERROR DETAIL (see Defined Error Detail Values) USER SENSE SV KEY SF KEY Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'2F' │ X'92' │ No Get is outstanding for this name, so cannot send │ │ │ │ │ response. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'17' │ X'01' │ The correlator given is incorrect. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'72' │ Invalid input received as data for sending the error │ │ │ │ │ sense code. Also, if the maximum I-field size is set │ │ │ │ │ to less than 512 and response results in NMVTs greater │ │ │ │ │ than 512 bytes, this error code is returned. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'62' │ X'60' │ Cannot talk to host. SSCP-PU session between Communi- │ │ │ │ │ cations Manager and host is not active. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.12.1. Defined SENSETYPE Values ═══ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SENSETYPE Values, Data, and Descriptions │ ├──────┬───────────┬───────────────────────────────────────────────────────────────────────────────┤ │ │ SENSE │ │ │ VALUE│ DATA │ DESCRIPTION │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 0 │ User │ A user-specified sense code is returned to the requestor. The user sense │ │ │ sense │ field in the ARB is used to give the user sense code to the host and must │ │ │ │ conform to SNA sense codes. │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 1 │ X'084B │ The target manager is not available. │ │ │ 0003' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 2 │ X'1003 │ The request is not accepted or supported by the target. │ │ │ 000D' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 3 │ X'081C │ The request is accepted by the target, but errors occurred during execution. │ │ │ 0n0m' │ │ │ │ │ n = X'A' or X'B'; m = 1 - 4. (n=LCCSTAT+9 and m=Error Detail ARB fields) │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 4 │ X'086F │ Invalid major vector (MV) length. │ │ │ 0001' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 5 │ X'086D │ Required SF (X'01') missing in SV (X'06'). │ │ │ 0601' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 6 │ X'080C │ Command subvector not recognized. │ │ │ 0006' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 7 │ X'086C │ Execute command subvector missing. │ │ │ 3100' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 8 │ X'086C │ Test setup data subvector missing. │ │ │ 8000' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 9 │ X'0806 │ Resource unknown. │ │ │ 0001' │ │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 10 │ X'086A │ SF (X'sf') key is invalid for SV (X'sv'). Use ARB fields SV Key and SF Key │ │ │ svsf' │ to show which subfield in which subvector is in error. │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 11 │ X'086B │ SF (X'sf') value is invalid for SV (X'sv'). Use ARB fields SV Key and SF Key │ │ │ svsf' │ to show which subfield in which subvector is in error. │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 12 │ X'086F │ Subvector (X'sv') length error. Use ARB field SV Key to show which subvector │ │ │ sv05' │ is in error. │ ├──────┼───────────┼───────────────────────────────────────────────────────────────────────────────┤ │ 13 │ X'086F │ Subfield length error. Use ARB field SF key to show which subvector contains │ │ │ sf06' │ the subfields in error. │ └──────┴───────────┴───────────────────────────────────────────────────────────────────────────────┘ ═══ 7.12.2. Defined LCCSTAT Values ═══ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Defined LCCSTAT Values │ ├──────┬───────────────────────────────────────────────────────────────────────────────────────────┤ │ VALUE│ DESCRIPTION │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 1 │ The link connection component (LCC) or the configuration file have recovered from the │ │ │ error. They are in a state prior to the execution of the command. │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 2 │ The LCC or the configuration file or both are in an unpredictable state. │ └──────┴───────────────────────────────────────────────────────────────────────────────────────────┘ ═══ 7.12.3. Defined Error Detail Values ═══ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Defined Error Detail Values │ ├──────┬───────────────────────────────────────────────────────────────────────────────────────────┤ │ VALUE│ DESCRIPTION │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 1 │ Memory error │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 2 │ File access error │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 3 │ LCCI error │ ├──────┼───────────────────────────────────────────────────────────────────────────────────────────┤ │ 4 │ Process error │ └──────┴───────────────────────────────────────────────────────────────────────────────────────────┘ ═══ 7.13. Send a Preformatted Unsolicited NMVT to the NetView Program ═══ Send a Preformatted Unsolicited NMVT to the NetView Program This function sends an unsolicited preformatted NMVT to the NetView program. One possible use for this capability is to send alert NMVTs that are already in host format (EBCDIC text and host format binary fields) to the NetView program. All unsolicited preformatted NMVT sent through this API must be less than or equal to 508 bytes (the SPA Router API processor adds the 8-byte NMVT header to reach the maximum of 512 bytes). Processing 1. Provide memory for an ARB. 2. Store ARB3 in the ARBID field of the ARB. 3. Store 96 in the ARB LENGTH field of the ARB. 4. Check that the target application name has been opened with SPA Router. 5. Store the target application name in the TARGET NAME field of the ARB. 6. Store 030DH in the REQUEST CODE field of the ARB. 7. Store the length of the NMVT in the PUTREPLY LENGTH field of the ARB. This must be less than or equal to 508 (bytes). 8. Store the address of the response NMVT in the PUTREPLY field of the ARB. This address must be of the memory buffer containing the preformatted NMVT that was dynamically allocated by the application using the OS/2 DosAllocSeg function with the flags set for the function call such that the buffer is shareable through both DosGiveSeg and DosGetSeg. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'13' │ Invalid length received for reply message from buffer │ │ │ │ │ or file. Also, if the maximum I-field size is set to │ │ │ │ │ less than 512 and response results in NMVTs greater │ │ │ │ │ than 512 bytes, this error code is returned. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'62' │ X'60' │ Cannot talk to host. SSCP-PU session between Communi- │ │ │ │ │ cations Manager and host is not active. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'09' │ Shared memory passed cannot be accessed by the SPA │ │ │ │ │ Router process. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.14. Close SPCF API ═══ Close SPCF API This function terminates the use of an application name in SPA Router. The resources reserved for the application that opened the target name are freed by SPA Router. The target name can be forced closed (FORCE is Y) to cause error sense to be sent to the host for all outstanding SPCF commands or messages. Processing 1. Check that the target application name has been opened with SPA Router. 2. Store 0304H in the REQUEST CODE field of the ARB. 3. If you want to force close the target name, store Y in the FORCE field of the ARB. Usage The SPCF subroutine. If using the C interface, CALL DCJVC0C and pass the address of the ARB as the single argument. For example, the format of the call could be rc = DCJVC0C (&ARB);. On Return: Check the return code in rc and the codes returned in the ARB (return code, class, type) to determine if there were any errors. Take the appropriate action for each error. ┌─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┐ │ RETURN CODE │ CLASS FIELD │ TYPE FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'00' │ X'00' │ X'00' │ Request processed without error. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'2F' │ Request code passed is invalid or the request needs a │ │ │ │ │ larger ARB to be valid. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'02' │ X'42' │ SPA Router is not running. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'35' │ X'xx' │ OS/2 error code xx was encountered while processing │ │ │ │ │ the request. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'41' │ X'46' │ Application name not open. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'01' │ X'72' │ Force Close field in ARB has a value other than X'Y' │ │ │ │ │ or X'N'. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'94' │ X'02' │ Application has not responded to all NMVTs received, │ │ │ │ │ so cannot close name without setting the FORCE field │ │ │ │ │ to Y. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ X'08' │ X'33' │ X'5F' │ Request NMVTs still queued for this application name, │ │ │ │ │ so cannot close name without setting the FORCE field │ │ │ │ │ to Y. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.15. SPCF ARB ═══ The format of the SPCF ARB and a description of the ARB fields is shown in SPCF ARB. The SPA Router header file described in API Data Structures provides the C language definition for the ARB structure. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SPCF ARB │ ├─────┬─────┬──────────┬───────────────────────────────────────────────────────────────────────────┤ │ DISP│ LGTH│ NAME │ DESCRIPTION │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 0 │ 04│ ARBID │ A 4-character constant that is used to verify the start of the ARB. The │ │ │ │ │ 4-character constant ARB3 must be stored in the ARBID field. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 4 │ 02│ REQUEST │ A word (2-byte Intel word)identifier. request identifier. request Each │ │ │ │ CODE │ request has a unique code that must be stored in the ARB by the applica- │ │ │ │ │ tion. The high-order byte identifies the function and the low-order byte │ │ │ │ │ identifies the request. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 6 │ 01│ ARB │ The length 96 of the ARB for this function. The length must be stored │ │ │ │ LENGTH │ into the ARB by the application. All new applications or applications │ │ │ │ │ wanting to take advantage of the receive queue semaphore or the ability │ │ │ │ │ to specify receive queue depth should specify a length of 96. For the │ │ │ │ │ sake of compatibility the length may be 90 if the application wants to │ │ │ │ │ use the 90-byte ARB from the NetView/PC 1.1 program. This ARB supported │ │ │ │ │ all request codes presently available except 0311H, open target name, and │ │ │ │ │ set receive queue depth. It also does not support the receive queue │ │ │ │ │ semaphore. For the sake of compatibility, the length may be 67 if the │ │ │ │ │ application wants to use the 67-byte ARB from the NetView/PC 1.0 program. │ │ │ │ │ The 67-byte ARB supports only the following request codes: 0301H, 0302H, │ │ │ │ │ 0303H, and 0304H. It does not support the receive queue semaphore. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 7 │ 01│ PARSE ID │ A 1-byte field returned by the API that contains the least significant │ │ │ │ │ byte of the major vector (MV) key of the command NMVT. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 8 │ 01│ Reserved │ Reserved and must be initialized to binary 0s. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 9 │ 02│ RETURN │ An indicator of the degree of success in performing the request. │ │ │ │ CODE │ │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 11│ 02│ CLASS │ The error class. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 13│ 02│ TYPE │ The error type. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 15│ 08│ TARGET │ An 8-character application name by which the application is known to the │ │ │ │ NAME │ host. If you wish to use a name shorter than 8 characters, you must pad │ │ │ │ │ the name on the right with blanks. No binary 0 character terminators │ │ │ │ │ should be used. This name is given in ASCII. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 23│ 01│ MSGTYPE │ (B|F) A 1-character keyword that indicates whether the message data to be │ │ │ │ │ sent is in a buffer or is in a message file. When MSGTYPE is B, the │ │ │ │ │ message data to be sent is in a buffer. When MSGTYPE is F, the message │ │ │ │ │ data to be sent is in a file. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 24│ 04│ MSGFILE │ When MSGTYPE is F, MSGFILE contains the exact 4-character name of the │ │ │ │ │ message file (whose extension is .MSG) that contains the message to be │ │ │ │ │ sent to the NetView program. This file must be in the current directory │ │ │ │ │ or in a directory that is in the current DPATH. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 28│ 04│ MSGNUM │ A 4-character numeric message identifier of the reply message in the file │ │ │ │ │ named in the MSGFILE field. The message identifier must be exactly 4 │ │ │ │ │ characters long. Leading character 0s are required for numbers less than │ │ │ │ │ 4 characters long. Message data from the file is translated from ASCII │ │ │ │ │ to EBCDIC before it is sent. This field should be 0 if the request is │ │ │ │ │ for anything other than a response sent from a message file. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 32│ 02│ MBLENGTH │ A word (16-bit integer) length of the binary data to be sent from the │ │ │ │ │ buffer pointed to by the MSGBUFF field. This field is only meaningful on │ │ │ │ │ RUNCMD responses (request code 0302H) when CONVERT is N. This field is │ │ │ │ │ not examined if CONVERT is Y because the length is computed from the │ │ │ │ │ message list lengths and the MSGCOUNT. The maximum length for this field │ │ │ │ │ is 32478. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 34│ 02│ MSGCOUNT │ A word (16-bit integer) count of the messages to be sent from the message │ │ │ │ │ buffer pointed to by the MSGBUFF field. This field should be 0 if │ │ │ │ │ message data to be sent is contained in a message file. This field │ │ │ │ │ should be 1 if the CONVERT field is N. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 36│ 01│ CONVERT │ (N|Y) 1-character keyword that indicates whether RUNCMD response message │ │ │ │ │ data is to be translated from ASCII to EBCDIC before it is sent (Y) or │ │ │ │ │ not (N) translated. The NetView RUNCMD does not handle unconverted (N) │ │ │ │ │ reply messages. When CONVERT is N, the message data is sent as is. Any- │ │ │ │ │ thing other than Y causes the data not to be translated (default to N). │ │ │ │ │ This field is only used for 0302H requests; otherwise, it is assumed to │ │ │ │ │ be Y. │ └─────┴─────┴──────────┴───────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SPCF ARB │ ├─────┬─────┬──────────┬───────────────────────────────────────────────────────────────────────────┤ │ DISP│ LGTH│ NAME │ DESCRIPTION │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 37│ 04│ MSGBUFF │ A 4-byte (word offset and word segment) address pointing to a buffer that │ │ │ │ │ contains message data to be sent by request code 0302H or 030AH. This │ │ │ │ │ buffer must be allocated dynamically by the application using the OS/2 │ │ │ │ │ DOSALLOCSEG function with the flags set for that function call such that │ │ │ │ │ the segment is shareable through both DOSGIVESEG and DOSGETSEG and is not │ │ │ │ │ discardable. In other words, bits 0 and 1 of the DOSALLOCSEG flag param- │ │ │ │ │ eter should be turned on and bit 2 should be turned off. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 41│ 01│ CMDLGTH │ A 1-byte length of the received message and pointed to by the COMMAND │ │ │ │ │ field of this ARB. The command length is set to 0 for a Receive a │ │ │ │ │ Command (0309H) request and the application must parse the NMVT to get │ │ │ │ │ the length. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 42│ 04│ COMMAND │ A 4-byte (word offset and word segment) address returned by the API │ │ │ │ │ pointing to the SPCF receive buffer that contains the received RUNCMD │ │ │ │ │ message through request code 0303H or the received unparsed SPCF NMVT │ │ │ │ │ through request code 0309H. The data in this buffer remains intact until │ │ │ │ │ one of the following events occurs: │ │ │ │ │ │ │ │ │ │ o The application successfully responds to the request. │ │ │ │ │ │ │ │ │ │ o The application responds to the request and receives the return code │ │ │ │ │ (8,23,65) that indicates that the correlator has been inactivated due │ │ │ │ │ to a loss of the host connection. │ │ │ │ │ │ │ │ │ │ o The application makes a successful close request for the target │ │ │ │ │ application name that received the command. │ │ │ │ │ │ │ │ │ │ o The application terminates. │ │ │ │ │ │ │ │ │ │ After any of these events occurs, the buffer may be reused on subsequent │ │ │ │ │ receive requests for the same target application name. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 46│ 10│ RECVCORR │ A 10-byte hex correlator. The unique correlator of the last message │ │ │ │ │ returned for a receive call. It must be stored in the SENDCORR field of │ │ │ │ │ the ARB when the reply is sent. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 56│ 10│ SENDCORR │ The 10-byte correlator of the message this send reply call is replying │ │ │ │ │ to. The correlator is used to associate the reply message with the │ │ │ │ │ received message (required for send calls). This field is ignored with │ │ │ │ │ SEND_MESSAGE requests. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 66│ 01│ FORCE │ (N|Y) One character keyword used with CLOSE that indicates whether mes- │ │ │ │ │ sages and commands destined for the application are discarded. Y causes │ │ │ │ │ queued messages and commands to be discarded, and error sense is sent to │ │ │ │ │ the host by the API. If N is specified and there are any outstanding │ │ │ │ │ commands for the specified target application name, the close request │ │ │ │ │ fails and the specified target application name remains open and an error │ │ │ │ │ return code (8,148,2) is returned. Anything other than Y or N returns an │ │ │ │ │ error return code. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ │ │ │ The following fields are used with request codes 0309H, 030AH, 030BH, │ │ │ │ │ 030CH, and 030DH. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 67│ 08│ OPERATOR │ An 8-character name of the NetView operator who will receive the unsolic- │ │ │ │ NAME │ ited message. If the name is less than 8 characters long, it must be │ │ │ │ │ padded on the right with blanks. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 75│ 02│ PUTREPLY │ A word (16-bit integer) length of the overall NMVT to be sent to the │ │ │ │ LENGTH │ NetView program. With the implementation of chaining, the size of the │ │ │ │ │ vector may be up to 32K, but no single major vector length may exceed 504 │ │ │ │ │ bytes. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 77│ 04│ PUTREPLY │ A 4-byte (word offset and word segment) address pointing to a buffer that │ │ │ │ │ contains the reply NMVT to be sent to the NetView program. This buffer │ │ │ │ │ must be allocated dynamically by the application using the OS/2 │ │ │ │ │ DOSALLOCSEG function with the flags set for that function call such that │ │ │ │ │ the segment is shareable through both DOSGIVESEG and DOSGETSEG and is not │ │ │ │ │ discardable. In other words, bits 0 and 1 of the DOSALLOCSEG flag param- │ │ │ │ │ eter should be turned on and bit 2 turned off. This address is used when │ │ │ │ │ the application chooses to send a response NMVT to the host through │ │ │ │ │ request code 030BH or 030DH. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 81│ 01│ SENSETYPE│ A 1-byte (8-bit integer) value that determines the sense code that is │ │ │ │ │ sent back to the NetView program when the Send Error Sense (X'030C') │ │ │ │ │ request code is used. This field is required for the Send error sense │ │ │ │ │ request. See SENSETYPE Values, Data, and Descriptions for values. │ └─────┴─────┴──────────┴───────────────────────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ SPCF ARB │ ├─────┬─────┬──────────┬───────────────────────────────────────────────────────────────────────────┤ │ DISP│ LGTH│ NAME │ DESCRIPTION │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 82│ 01│ LCCSTAT │ A 1-byte (8-bit integer) value of the secondary sense code that is sent │ │ │ │ │ back to the NetView program when the Send error sense (X'030C') request │ │ │ │ │ code is used. This field is optional for the Send error sense request │ │ │ │ │ and must be set to X'00' if not used. See Defined LCCSTAT Values for │ │ │ │ │ values. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 83│ 01│ ERROR │ A 1-byte (8-bit integer) value of the error detail that is sent back to │ │ │ │ DETAIL │ the NetView program when the Send error sense (X'030C') request code is │ │ │ │ │ used. This field is optional for the Send error sense request and must │ │ │ │ │ be set to X'00' if not used. See Defined Error Detail Values for values. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 84│ 04│ USER │ A 4-byte binary user string sense code. The sense code must conform to │ │ │ │ SENSE │ SNA sense codes. This field is used if the SENSETYPE is 0. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 88│ 01│ SV KEY │ A 1-byte binary field to put the key of the subvector with the error in. │ │ │ │ │ This field is optional and must be set to 0 if not used. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 89│ 01│ SF KEY │ A 1-byte binary field to put the key of the subfield with the error in. │ │ │ │ │ This field is optional and must be set to 0 if not used. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 90│ 01│ QUEUE │ A 1-byte binary field that specifies the number of commands that the │ │ │ │ DEPTH │ application wants the SPCF router to queue up from the host without the │ │ │ │ │ application performing a receive. The range is from 1 to 32. Each addi- │ │ │ │ │ tional queue uses 512 bytes of memory. This field is only used on 0311H │ │ │ │ │ requests. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 91│ 01│ Reserved │ A 1-byte reserved binary field that should be set to 0. │ ├─────┼─────┼──────────┼───────────────────────────────────────────────────────────────────────────┤ │ 92│ 04│ RECEIVE │ The SPCF API returns the handle of a semaphore that is used to indicate │ │ │ │ QUEUE │ to the application when a command is available for the target application │ │ │ │ SEMAPHORE│ name being opened. This field is returned only on successful open │ │ │ │ HANDLE │ requests (0301H) with an ARB length of at least 96 and on successful open │ │ │ │ │ and set queue depth requests (0311H) that also require an ARB length of │ │ │ │ │ at least 96. This semaphore is cleared when there is a command in the │ │ │ │ │ receive queue of the target application name that it is associated with. │ │ │ │ │ Use of this semaphore is highly recommended, because it allows the appli- │ │ │ │ │ cation to receive commands without polling. │ └─────┴─────┴──────────┴───────────────────────────────────────────────────────────────────────────┘ ═══ 7.16. SPCF API Return Codes (DCJVC0C Return Codes) ═══ When NMVTs are sent out to the host, SPA Router passes back return codes to the caller at API completion. See Return Codes for SPCF Subroutine. These return codes are actually the return codes from the APPC communications facility. When the APPC return codes indicate an OK status, it means that APPC received the SPCF NMVT and scheduled it for transmission to the SSCP (host). This does not guarantee that the SPCF NMVT was received by the NetView Hardware Monitor, since it may be lost at a number of points on the path to the host. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Return Codes for SPCF Subroutine │ ├─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┤ │ RETURN │ CLASS │ TYPE │ │ │ CODE │ FIELD │ FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 0 (X'0') │ 0 (X'0') │ 0 (X'0') │ Request processed without error │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 2 (X'02') │ 0 (X'0') │ 0 (X'0') │ Queue empty │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE No commands outstanding. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Try later. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 2 (X'02') │ 1 (X'01') │ 26 (X'1A') │ Queue empty due to invalid RUNCMD processing │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE An invalid RUNCMD was received from the │ │ │ │ │ host for the target application name, so no │ │ │ │ │ command request is available. The differ- │ │ │ │ │ ence between this return code and the return │ │ │ │ │ code indicating an empty queue for which no │ │ │ │ │ commands are outstanding is that for this │ │ │ │ │ return code there are commands in the queue │ │ │ │ │ at the start of processing but one or all │ │ │ │ │ were rejected due to an invalid format. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Issue the call again for other com- │ │ │ │ │ mands. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 9 (X'09') │ Storage cannot be accessed │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Storage given to SPCF router is not │ │ │ │ │ shared. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Get shared storage and try again. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 19 (X'13') │ Invalid length received │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Length of a field is too long or too │ │ │ │ │ short: │ │ │ │ │ │ │ │ │ │ For Preformatted Reply - if less than 4 or │ │ │ │ │ first MV is greater than 504 bytes │ │ │ │ │ │ │ │ │ │ For RUNCMD Reply - if unformatted reply │ │ │ │ │ length = 0 │ │ │ │ │ │ │ │ │ │ For any type of solicited reply - NMVT │ │ │ │ │ created is greater than 32 bytes │ │ │ │ │ │ │ │ │ │ For SPMSG - if operator length is less than │ │ │ │ │ 1 or greater than 8 │ │ │ │ │ │ │ │ │ │ For any type of unsolicited reply - NMVT │ │ │ │ │ created is greater than the maximum I-field │ │ │ │ │ size. │ │ │ │ │ │ │ │ │ │ For any reply - SPCF Router builds and sub- │ │ │ │ │ vector would exceed 255 bytes. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Send valid amount of data. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 28 (X'1C') │ Queue depth requested is not acceptable │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The queue depth specified in the open │ │ │ │ │ request is not within the allowed range. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Issue the call again specifying a │ │ │ │ │ queue depth from 1 to the maximum allowed. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 44 (X'2C') │ Invalid reply count SV │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE On a reformatted SEND, the reply count │ │ │ │ │ subvector is missing, does not have the │ │ │ │ │ correct subfields, or has invalid lengths. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Application should be corrected to │ │ │ │ │ include a valid reply count subvector and │ │ │ │ │ try again. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Return Codes for SPCF Subroutine │ ├─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┤ │ RETURN │ CLASS │ TYPE │ │ │ CODE │ FIELD │ FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 47 (X'2F') │ Invalid request code │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The request code in the ARB request │ │ │ │ │ code field is not a valid request code for │ │ │ │ │ the SPCF API. This may be because the │ │ │ │ │ request code alone is invalid or it may be │ │ │ │ │ that the request code is invalid for the │ │ │ │ │ length of the ARB that is being passed or │ │ │ │ │ the ARB length specified in the ARB LENGTH │ │ │ │ │ field is not long enough to support the │ │ │ │ │ request code specified. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Put a valid request code in the ARB │ │ │ │ │ REQUEST CODE field of an ARB that is long │ │ │ │ │ enough to support that request code. Put │ │ │ │ │ the length of the ARB in the ARB LENGTH │ │ │ │ │ field and provide an ARB that is long enough │ │ │ │ │ to support that request code. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 72 (X'48') │ Invalid MSGTYPE │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE When a SPCF API call is made to send a │ │ │ │ │ RUNCMD response or a message to a NetView │ │ │ │ │ operator, the MSGTYPE field in the ARB │ │ │ │ │ passed contains an invalid value. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Put a capital B in the MSGTYPE │ │ │ │ │ field of the ARB if the message is in a │ │ │ │ │ buffer in memory or put a capital F if the │ │ │ │ │ message is in a message file. Retry the │ │ │ │ │ call. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 1 (X'01') │ 114 (X'72') │ Invalid input received │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Bad data received: │ │ │ │ │ │ │ │ │ │ If RUNCMD reply with messages, but no mes- │ │ │ │ │ sages. │ │ │ │ │ │ │ │ │ │ If ERROR reply, and SENSETYPE indicate that │ │ │ │ │ additional parameters contain information, │ │ │ │ │ but those parameters are missing. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Correct the call to SPCF Router. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 2 (X'02') │ 66 (X'42') │ SPA Router not active │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE SPA Router is not running in the │ │ │ │ │ system. Note that autolaunching of SPA │ │ │ │ │ Router (any SPCF API call starts the SPA │ │ │ │ │ Router if it is not running already) is not │ │ │ │ │ supported. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Start SPA Router and then retry. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 2 (X'02') │ 68 (X'44') │ Attempt to OPEN the specified message file failed │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE When a call is made to the SPCF API to │ │ │ │ │ send a RUNCMD response or a message to a │ │ │ │ │ NetView operator, the MSGTYPE field in the │ │ │ │ │ ARB is set to F, indicating that the │ │ │ │ │ response is in a message file, the opening │ │ │ │ │ of the file specified in the MSGFILE field │ │ │ │ │ of the ARB failed. A file name that is not │ │ │ │ │ exactly 4 characters long can cause this │ │ │ │ │ error. Another likely cause is that the │ │ │ │ │ file specified in the MSGFILE field of the │ │ │ │ │ ARB (XXXX.MSG) is not in the current direc- │ │ │ │ │ tory and is not in any of the subdirectories │ │ │ │ │ listed in the DPATH of the calling applica- │ │ │ │ │ tion environment. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Correct the file name if it is │ │ │ │ │ incorrect. Modify the DPATH of the calling │ │ │ │ │ application to include the subdirectory in │ │ │ │ │ which the message file resides if the │ │ │ │ │ message file does not reside in the current │ │ │ │ │ directory. Then retry the call. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Return Codes for SPCF Subroutine │ ├─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┤ │ RETURN │ CLASS │ TYPE │ │ │ CODE │ FIELD │ FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 2 (X'02') │ 72 (X'48') │ Message not found │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE When a call is made to the SPCF API to │ │ │ │ │ send a RUNCMD response or a message to a │ │ │ │ │ NetView operator, the MSGTYPE field in the │ │ │ │ │ ARB is set to F indicating that the response │ │ │ │ │ is in a message file, the specified message │ │ │ │ │ is not found in the file specified in the │ │ │ │ │ MSGFILE field of the ARB. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Check to make sure that the message │ │ │ │ │ file name specified in the MSGFILE field of │ │ │ │ │ the ARB is correct. Check to make sure that │ │ │ │ │ the MSGNUM field in the ARB is the character │ │ │ │ │ representation of a 4-character message │ │ │ │ │ number (with leading 0s (not blanks) if nec- │ │ │ │ │ essary to fill the 4 characters) that is │ │ │ │ │ contained in the specified message file. │ │ │ │ │ Verify that the message file is in the │ │ │ │ │ format required by the API. After cor- │ │ │ │ │ recting any of these problems, retry the │ │ │ │ │ call. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 10 (X'0A') │ 4 (X'04') │ Maximum number of applications already open in the │ │ │ │ │ system │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The maximum number of applications │ │ │ │ │ (usually set to 128) is already open in the │ │ │ │ │ system. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Close another application or wait │ │ │ │ │ and try later. Also, the maximum applica- │ │ │ │ │ tion parameter (/MAXREGAPP option in RTR │ │ │ │ │ CONFIG command) can be increased (up to 128) │ │ │ │ │ to allow more application names in the │ │ │ │ │ system. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 17 (X'11') │ 70 (X'46') │ The target application name specified in the TARGET │ │ │ │ │ NAME field of the ARB is already opened │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE An SPCF API open target application │ │ │ │ │ name call was made, but the specified target │ │ │ │ │ application name is already currently open │ │ │ │ │ in the system. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION If the target name was not opened │ │ │ │ │ by the current application, the application │ │ │ │ │ cannot use this name and must open with some │ │ │ │ │ other name. However, if the name was actu- │ │ │ │ │ ally opened by the current application, it │ │ │ │ │ should proceed with whatever subsequent SPCF │ │ │ │ │ API requests that it wants to perform. If │ │ │ │ │ the application has a need to reopen the │ │ │ │ │ interface for the specified target applica- │ │ │ │ │ tion name, the application program should │ │ │ │ │ first make a call to close the target appli- │ │ │ │ │ cation name specified so that it may be reo- │ │ │ │ │ pened. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 23 (X'17') │ 1 (X'01') │ Invalid CORRID │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The CORRID given on the SEND is not one │ │ │ │ │ of the outstanding CORRIDs for this applica- │ │ │ │ │ tion. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Only SEND with CORRIDs received on │ │ │ │ │ RECEIVEs. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 27 (X'1B') │ 79 (X'4F') │ Unused or closed control block │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The target name is not open, so it │ │ │ │ │ cannot be closed. However, it could also be │ │ │ │ │ that some other process has opened this │ │ │ │ │ target name, in which case this process │ │ │ │ │ cannot close it. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION No need to close the target name. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Return Codes for SPCF Subroutine │ ├─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┤ │ RETURN │ CLASS │ TYPE │ │ │ CODE │ FIELD │ FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 47 (X'2F') │ 146 (X'92') │ No RECEIVE outstanding │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Cannot SEND when no RECEIVEs are out- │ │ │ │ │ standing. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION RECEIVE a command from the host │ │ │ │ │ first. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 49 (X'31') │ 9 (X'09') │ Sufficient memory is not available │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The API was not able to successfully │ │ │ │ │ allocate enough memory to satisfy the open │ │ │ │ │ API requested. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Terminate one or more of the other │ │ │ │ │ applications that is running or modify the │ │ │ │ │ configuration of SPA Router or the OS/2 │ │ │ │ │ program in order to free enough memory to │ │ │ │ │ allow the API enough memory to successfully │ │ │ │ │ perform the open request. Then retry the │ │ │ │ │ call. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 51 (X'33') │ 95 (X'5F') │ Requests still queued │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Not all commands sent from the host to │ │ │ │ │ the application have been received. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Receive and reply to commands or │ │ │ │ │ CLOSE FORCE. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 53 (X'35') │ XXX │ OS/2 error │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE A request made of the API caused the │ │ │ │ │ API to issue an OS/2 call that resulted in │ │ │ │ │ an OS/2 error. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Refer to the explanations in the │ │ │ │ │ OS/2 Technical Library. The error type xxx │ │ │ │ │ returned in the API ARB is the error return │ │ │ │ │ code that was returned by the OS/2 program. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 65 (X'41') │ 70 (X'46') │ The target application name specified in the TARGET │ │ │ │ │ NAME field of the ARB is not open for the calling │ │ │ │ │ process │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE A request was made of the SPCF API │ │ │ │ │ routine to perform a service when the target │ │ │ │ │ application name specified in the TARGET │ │ │ │ │ NAME field of the ARB is not currently open │ │ │ │ │ for the calling application program (the │ │ │ │ │ process). │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Make an open request to the SPCF │ │ │ │ │ API for the desired target application name │ │ │ │ │ and then retry the call. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 70 (X'46') │ 3 (X'03') │ Application already open │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE An application with the same name is │ │ │ │ │ already open. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Try to open with another name. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 76 (X'4C') │ 98 (X'62') │ Request cannot be parsed │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The command received from the host is │ │ │ │ │ not a RUNCMD. Only RUNCMD parsing is sup- │ │ │ │ │ ported by SPCF API. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Reissue the RECEIVE with NOPARSE │ │ │ │ │ option. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 98 (X'62') │ 96 (X'60') │ Host system not available │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Cannot communicate to host. SSCP-PU │ │ │ │ │ session between Communications Manager and │ │ │ │ │ the NetView program is not active. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Check the connectivity setting for │ │ │ │ │ Communications Manager. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Return Codes for SPCF Subroutine │ ├─────────────┬─────────────┬─────────────┬────────────────────────────────────────────────────────┤ │ RETURN │ CLASS │ TYPE │ │ │ CODE │ FIELD │ FIELD │ DESCRIPTION │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 148 (X'94') │ 2 (X'02') │ SEND still outstanding │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE Not all commands received by applica- │ │ │ │ │ tion have been responded to. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION Respond to outstanding SENDs or │ │ │ │ │ CLOSE FORCE. │ ├─────────────┼─────────────┼─────────────┼────────────────────────────────────────────────────────┤ │ 8 (X'08') │ 148 (X'94') │ 146 (X'92') │ Too many RECEIVEs outstanding │ │ │ │ │ │ │ │ │ │ PROBABLE CAUSE The maximum number (8) of commands has │ │ │ │ │ already been received. │ │ │ │ │ │ │ │ │ │ RECOMMENDED ACTION The application should reply to │ │ │ │ │ some of the outstanding commands. │ └─────────────┴─────────────┴─────────────┴────────────────────────────────────────────────────────┘ ═══ 7.17. Error Conditions Not Reported in ARB Return Codes ═══ There are certain error conditions that make it impossible for the SPCF API to return error codes to the caller in the ARB. This is usually because the ARB address passed by the caller is of questionable validity. These circumstances are signaled in the assembler interface by setting AX and DX to 0 on return to the caller. These circumstances are signaled in the high-level language interface by setting the value returned in the AX register to -1. Regardless of the interface used, the values returned in the return code slots of the ARB are meaningless under these circumstances, as these values remain the same as they were before the call to the SPCF API was made. For this reason, it is a good practice to initialize the return code slots in the ARB prior to each call to the SPCF API to a value that is never returned by the SPCF API, such as -1, in order to avoid being misled by leftover return codes. The following are errors that can cause the SPCF API to regard the ARB address passed as invalid: 1. The first 4 characters located at the ARB address passed are not the ARB ID (ARB3) required by the SPCF API routine being called. There can be several reasons for this: a. An invalid ARB address was passed. b. A valid ARB address was passed, but the ARB ID is not set up or is set up with an incorrect character string (one other than ARB3). 2. The ARB address passed to the API is invalid because a minimum length ARB would extend beyond the end of the segment pointed to by the ARB address. 3. The ARB address passed to the API is invalid because an ARB of the length specified in the length field of the ARB would extend beyond the end of the segment pointed to by the ARB address. This case can be caused by either an invalid ARB address or an invalid value in the ARB length field of the ARB passed. Note: Be sure that the assembler or compiler that is being used is putting the fields of the ARB on byte boundaries. Many compilers (by default) put fields in structures on word boundaries. ARBs that have extra bytes inserted by the compiler may cause a wide variety of errors. ═══ 7.18. NetView Commands Supported by SPA Router ═══ The following NetView commands are supported by SPA Router: LINKDATA LINKPD LINKTEST RUNCMD ═══ 7.19. LINKDATA ═══ LINKDATA The LINKDATA command obtains data from a service point. Format >>──LINKDATA──SP=service point name,──APPL=application name,──┬─LINE=line name─────────┬───────────> └─RESOURCE=resource name─┘ >──┬────────────────────┬──┬─────────────────────────┬────────────────────────────────────────────>< ├─,UN=using node─────┤ ├─,RD=remote device(node)─┤ └─,ENTRYLCC=entryLCC─┘ └─,EXITLCC=exitLCC────────┘ Example Remarks ═══ <hidden> service point name ═══ Specifies the name of the service point to execute the command. ═══ <hidden> application name ═══ Specifies the name of the link connection subsystem manager (LCSM) to execute the command. ═══ <hidden> line name ═══ Identifies the line name of the link connection. ═══ <hidden> resource name ═══ Identifies the name of the link connection component within a link connection. ═══ <hidden> using node ═══ Identifies the name of the primary link station for an unbalanced mode link or either node that contains the link station of a balanced mode link. ═══ <hidden> entry LCC ═══ Identifies the name of the first (entry) link connection component of a link connection. ═══ <hidden> remote device node ═══ Identifies the name of the secondary (adjacent) link station for an unbalanced mode link or the other node containing a link station of a balanced mode link. ═══ <hidden> exit LCC ═══ Identifies the name of the last (exit) link connection component of a link connection. ═══ <hidden> Remarks ═══ o ENTRYLCC and EXITLCC can be used to limit the data received. o This command can be issued from a CLIST to help automate problem determination and error recovery. o If LINKDATA is issued from a CLIST, the resulting data is returned to the CLIST for its use. If LINKDATA is issued from a command line, the results are displayed on your terminal on one or more LINKDATA REPLY panels. ═══ <hidden> Example ═══ To send a LINKDATA command to service point NMWS1 to retrieve data on line LIN3, enter: LINKDATA SP=NMWS1,APPL=APPL17,LINE=LIN3 APPL17 is the LCSM that executes the command. ═══ 7.20. LINKPD ═══ LINKPD The LINKPD command requests a service point to do problem determination analysis on a given link or link segment. Format >>──LINKPD──SP=service point name,──APPL=application name,──┬─LINE=line name────────┬──────────────> └─RESOURCEresource name─┘ >──┬────────────────────┬──┬─────────────────────────┬────────────────────────────────────────────>< ├─,UN=using node─────┤ ├─,RD=remote device(node)─┤ └─,ENTRYLCC=entryLCC─┘ └─,EXITLCC=exitLCC────────┘ Example Remarks ═══ <hidden> service point name ═══ Specifies the name of the service point to execute the command. ═══ <hidden> application name ═══ Specifies the name of the line connection subsystem manager (LCSM) to execute the command. ═══ <hidden> line name ═══ Identifies the line name of the link connection. ═══ <hidden> resource name ═══ Identifies the name of the link connection component within a link connection. ═══ <hidden> using node ═══ Identifies the name of the primary link station for an unbalanced mode link or either node that contains the link station of a balanced mode link. ═══ <hidden> entry LCC ═══ Identifies the name of the first (entry) link connection component of a link connection. ═══ <hidden> remote device node ═══ Identifies the name of the secondary (adjacent) link station for an unbalanced mode link or the other node containing a link station of a balanced mode link. ═══ <hidden> exit LCC ═══ Identifies the name of the last (exit) link connection component of a link connection. ═══ <hidden> Remarks ═══ o ENTRYLCC and EXITLCC can be used to narrow down the data received. o This command can be issued from a CLIST to help automate problem determination and error recovery. o If LINKPD is issued from a CLIST, the resulting data is returned to the CLIST and to your terminal as a message or messages. ═══ <hidden> Example ═══ To send a LINKPD command to service point (SP) NMWS1 to do a problem analysis on line LIN3, enter: LINKPD SP=NMWS1,APPL=APPL17,LINE=LIN3 APPL17 is the link connection subsystem manager that executes the command. ═══ 7.21. LINKTEST ═══ LINKTEST The LINKTEST command requests a service point to test a given link or link segment. Format >>──LINKTEST──SP=service point name,──APPL=application name,──┬─LINE=line name─────────┬───────────> └─RESOURCE=resource name─┘ >──┬────────────────────┬──┬─────────────────────────┬──┬──────────────────────────────────┬──────>< ├─,UN=using node─────┤ ├─,RD=remote device(node)─┤ └─,SELFCNT={number of repetitions}─┘ └─,ENTRYLCC=entryLCC─┘ └─,EXITLCC=exitLCC────────┘ Example Remarks ═══ <hidden> service point name ═══ Specifies the name of the service point to execute the command. ═══ <hidden> application name ═══ Specifies the name of the link connection subsystem manager (LCSM) to execute the command. ═══ <hidden> line name ═══ Identifies the line name of the link connection. ═══ <hidden> resource name ═══ Identifies the name of link connection component within a link connection. ═══ <hidden> using node ═══ Identifies the name of the primary link station for an unbalanced mode link or either node that contains the link station of a balanced mode link. ═══ <hidden> entry LCC ═══ Identifies the name of the first (entry) link connection component of a link connection. ═══ <hidden> remote device node ═══ Identifies the name of the secondary (adjacent) link station for an unbalanced mode link or the other node containing a link station of a balanced mode link. ═══ <hidden> exit LCC ═══ Identifies the name of the last (exit) link connection component of a link connection. ═══ <hidden> number of repetitions ═══ Specifies the number of self-test repetitions to be executed. The range is 1-255, with default = 1. ═══ <hidden> Remarks ═══ o ENTRYLCC and EXITLCC can be used to narrow down the data received. o This command can be issued from a CLIST to help automate problem determination and error recovery. o If LINKTEST is issued from a CLIST, the resulting data is returned to the CLIST for its use. If LINKTEST is used from a command line, the results are displayed at your terminal on one or more LINKTEST REPLY panels. ═══ <hidden> Example ═══ To send a LINKTEST command to service point NMWS1 to perform a test on line LIN3, enter: LINKTEST SP=NMWS1,APPL=APPL17,LINE=LIN3 APPL17 is the application that will execute the command. ═══ 7.22. RUNCMD ═══ RUNCMD The RUNCMD routes commands to service points for execution by one of the service point applications. Format >>──RUNCMD──SP=service point name,──APPL=application name,──command string────────────────────────>< Example Remarks Response ═══ <hidden> service point name ═══ Specifies the network name of the service point that is to receive the given command. ═══ <hidden> application name ═══ Specifies the name of the application that is to execute the given command. ═══ <hidden> command string ═══ Specifies the command to be executed. Each service point application defines the syntax of the command that is passed within command string. For ROP Service the format of command string is the following: >>──OP=operator ID──???──┬──────────────────┬──┬───────────────┬──┬──────────────────────────┬─────> └─PASS=password???─┘ └─RCO=option???─┘ └─WSID=workstation ID──???─┘ >──OS/2 command───────────────────────────────────────────────────────────────────────────────────>< ═══ <hidden> operator ID ═══ Specifies the operator ID of the NetView account issuing the command. ═══ <hidden> password ═══ Specifies the UPM password (on the OS/2 workstation) for the operator ID. The password is optional. ═══ <hidden> workstation ID ═══ Specifies the workstation to which a command is directed. ═══ <hidden> option ═══ Indicates the format of the response returned to the NetView program for the command being issued. If option is YES, ROP Service returns only the return code. If option is NO, ROP Service returns the response to the command. This parameter affects only the command currently being issued. This parameter is optional. ═══ <hidden> OS/2 ═══ The command to be executed on the OS/2 workstation. Note: The limit on the length of the RUNCMD is 240 characters. ═══ <hidden> Remarks ═══ The parameters on the RUNCMD are positional. The given command (command string) must be the last parameter. ═══ <hidden> Example ═══ o To issue DIR C: to ROP Service, type: RUNCMD SP=THX350, APPL=REMOTEOP, OP=TED1;PASS=D3X45Y; RCO=ON; DIR C: o To query the status of all monitored LAN segments in IBM LAN Manager, type: RUNCMD SP=THX350, APPL=LANMGR,10 o To issue DIR C: through ROP Service to an ESP workstation, type: RUNCMD SP=THX350, APPL=REMOTEOP, OP=TED1;WSID=WS001066; DIR C: ═══ <hidden> Response ═══ The normal response to RUNCMD is either messages from the service point application or message DSI260I RUNCMD COMPLETE when no messages are returned from the service point application. The messages returned may be ROP Service or service point application messages. ═══ 8. Developing Applications to Interact with ROP Service ═══ Developing Applications to Interact with ROP Service The API for ROP Service enables other applications to interact with ROP Service. It uses a dynamically linked library to access information from the executing ROP Service. This section describes each function call and presents the API data structures. Related Topic: API Function Calls ═══ 8.1. API Function Calls ═══ The following function calls are included in this section: ROPCmdDel ROPCmdEnum ROPCmdGetInfo ROPCmdStart ROPConfigGetInfo ROPConfigSetInfo ROPLogGetInfo ROPLogSetInfo ROPStart ROPStop ROPTblAddCmd ROPTblDelCmd ROPTblGetInfo ROPTblSwtch This section contains a description of each ROP Service API function call. The following information is included for each function call: o Syntax o Return codes o Remarks o Example ═══ 8.2. ROPCmdDel ═══ ROPCmdDel The ROPCmdDel function deletes the instance of a specific command from ROP Service. Format #include <ropapi.h> unsigned far pascal ROPCmdDel( CmdID ) unsigned short CmdID; Example Return Codes ═══ <hidden> CmdID ═══ Specifies the ID of the command that is to be deleted. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; rc = ROPCmdDel(0); // Delete command ID 0 if (rc) printf("ERROR - ROPCmdDel return code %d\n",rc); else printf("Command deletion successful\n"); exit(rc); } ═══ 8.3. ROPCmdEnum ═══ ROPCmdEnum The ROPCmdEnum function returns information regarding the commands currently being processed by ROP Service. Format #include <ropapi.h> unsigned far pascal ROPCmdEnum(level, buf, buflen, entriesread, totalentries); unsigned short level; char far * buf; unsigned short buflen; unsigned short far * entriesread; unsigned short far * totalentries; Example Return Codes Remarks ═══ <hidden> level ═══ Specifies the level of information to return. Valid values are 0, 1, and 2. ═══ <hidden> buf ═══ Points to the cmd_info_n data structure (where n is the level specified). See API Data Structures for information about the cmd_info_n data structure. ═══ <hidden> buflen ═══ Specifies the size (in bytes) of the buf memory area. ═══ <hidden> entriesread ═══ Points to the variable where the number of entries read is returned. ═══ <hidden> totalentries ═══ Points to the variable where the total number of entries read is returned. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_MORE_DATA │ 1001 │ More data was available than could be returned in the │ │ │ │ buffer provided. Issue the function call again speci- │ │ │ │ fying a larger buffer size. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPCmdEnum is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPCmdEnum is not as large as is │ │ │ │ stated in buflen. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Remarks ═══ The first 16 bytes of the buffer that are returned are reserved. Thus, the command array starts 16 bytes into the buffer. ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { SEL selROP; // selector for data buffer USHORT usbuflen; // length of data buffer USHORT i; // index for for-loop USHORT rc; // return code USHORT usEntriesRead; // number of entries read USHORT usTotalEntries; // total number of entries available BYTE FAR *pbBuf; // pointer to data buffer cmd_info_0 FAR *pCmdArray; // pointer to command array // // Allocate memory for API call. Since this call uses an array structure, // the extra reserved bytes must be allocated manually. // usbuflen = 10*sizeof(cmd_info_0)+ROP_API_RESERVED; rc = DosAllocSeg(usbuflen,&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pbBuf = MAKEP(selROP,0); rc = ROPCmdEnum( 0, // level 0 pbBuf, // data buffer usbuflen, // length of data buffer &usEntriesRead, // number of entries read &usTotalEntries); // total number of entries if (rc){ printf("Error ROPCmdEnum return code %d\n",rc); }else{ // // Array information starts after the reserved bytes // pCmdArray = (cmd_info_0 FAR *)MAKEP(selROP,ROP_API_RESERVED); // // Loop through commands and print command names and ids // printf("List of commands\n"); for (i=0;i<usEntriesRead;i++){ printf("Command %ld [%s]/n",pCmdArray[i].id,pCmdArray[i].cmd); } } DosFreeSeg(selROP); exit(rc); } ═══ 8.4. ROPCmdGetInfo ═══ ROPCmdGetInfo The ROPCmdGetInfo function returns information regarding a specific command. Format #include <ropapi.h> unsigned far pascal ROPCmdGetInfo( level, CmdID, buf ) unsigned short level; unsigned short CmdID; char far * buf; Example Return Codes Remarks ═══ <hidden> level ═══ Specifies the level of information to return. Valid values are 0, 1, and 2. ═══ <hidden> CmdID ═══ Specifies the ID of the command whose information is desired. ═══ <hidden> buf ═══ Points to the cmd_info_n data structure (where n is the level specified). See API Data Structures for information about the cmd_info_n data structure. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPCmdGetInfo is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPCmdGetInfo is not as large as is │ │ │ │ stated in buflen. Or, the buffer length is not large │ │ │ │ enough to hold a structure of the level specified. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Remarks ═══ The first 16 bytes of the buffer that are returned are reserved. Thus, the command record starts 16 bytes into the buffer. ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { SEL selROP; // selector for data buffer USHORT usbuflen; // length of data buffer USHORT rc; // return code BYTE FAR *pbBuf; // pointer to data buffer cmd_info_2 FAR *pCmdInfo2; // pointer to command array // // Allocate memory for API call. Since this call uses an array structure, // the extra reserved bytes must be allocated manually. // usbuflen = sizeof(cmd_info_2)+ROP_API_RESERVED; rc = DosAllocSeg(usbuflen,&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pbBuf = MAKEP(selROP,0); rc = ROPCmdGetInfo( 2,0,pbBuf); if (rc){ printf("Error ROPCmdGetInfo return code %d\n",rc); }else{ // // Array information starts after the reserved bytes // pCmdInfo2 = (cmd_info_2)MAKEP(selROP,ROP_API_RESERVED); printf("ID : %ld\n",pCmdInfo2->id); printf("Command Name : %s\n",pCmdInfo2->cmd); printf("Parameter : %s\n",pCmdInfo2->param); printf("Status : %ld\n",pCmdInfo2->status); printf("Time started : %s\n",pCmdInfo2->fmtstime); printf("Time ended : %s\n",pCmdInfo2->fmtetime); printf("Sessions ID : %d\n",pCmdInfo2->sessionid); } DosFreeSeg(selROP); exit(rc); } ═══ 8.5. ROPCmdStart ═══ ROPCmdStart The ROPCmdStart function executes a local instance of a command. Format #include <ropapi.h> unsigned far pascal ROPCmdStart( buf, buflen ) char far * buf; unsigned short buflen; Example Return Codes ═══ <hidden> buf ═══ Points to a buffer containing the name of the command to be started. ═══ <hidden> buflen ═══ Specifies the length of the buffer that is being passed. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPCmdStart is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPCmdStart is not as large as is │ │ │ │ stated in buflen. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <string.h> // C string library header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; CHAR pszCommand[260]; strcpy(pszCommand,"DIR C:"); rc = ROPCmdStart(pszCommand,strlen(pszCommand)); if (rc) printf("ERROR - ROPCmdStart return code %d\n",rc); else printf("Command successfully started\n"); exit(rc); } ═══ 8.6. ROPConfigGetInfo ═══ ROPConfigGetInfo The ROPConfigGetInfo function retrieves configuration information for ROP Service. Format #include <ropapi.h> unsigned far pascal ROPConfigGetInfo( buf ); char far * buf; Example Return Codes ═══ <hidden> buf ═══ Points to the cfg_info data structure. Example ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPConfigGetInfo is not a valid │ │ │ │ buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPConfigGetInfo is not large enough │ │ │ │ to contain the cfg_info structure. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { SEL selROP; // selector for data buffer USHORT rc; // return code cfg_info FAR *pCfgData; // pointer to command array // // Allocate memory for API call. // rc = DosAllocSeg(sizeof(cfg_info),&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pCfgData = (cfg_info FAR *)MAKEP(selROP,0); rc = ROPConfigGetInfo( pCfgData ); if (rc){ printf("Error ROPConfigGetInfo return code %d\n",rc); }else{ printf("Work path : %s\n",pCfgData->WrkPath); printf("NetView Application name : %s\n",pCfgData->NVApplName); printf("Command Validation Table name : %s\n",pCfgData->CmdTblName); printf("Maximum number of concurrent commands : %d\n",pCfgData->MaxCmds); printf("Minimum Long-running time : %d\n",pCfgData->MinLR); printf("Timeout value : %d\n",pCfgData->MaxLR); printf("PM user interface : %s\n",pCfgData->PMflag?"ON":"OFF"); printf("Reply with return code only : %s\n",pCfgData->ReplyCodeOnly?"ON":"OFF"); printf("UPM operator validation : %s\n",pCfgData->UPMcheck?"ON":"OFF"); printf("NetBIOS adapter number : %d\n",pCfgData->adap_num); } DosFreeSeg(selROP); exit(rc); } ═══ 8.7. ROPConfigSetInfo ═══ ROPConfigSetInfo The ROPConfigSetInfo function defines configuration parameters for ROP Service. Format #include <ropapi.h> unsigned far pascal ROPConfigSetInfo(buf); char far * buf; Example Return Codes ═══ <hidden> buf ═══ Points to the cfg_info data structure. See Configuration Information for information about the cfg_info data structure. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPConfigSetInfo is not a valid │ │ │ │ buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPConfigSetInfo is not large enough │ │ │ │ to contain the cfg_info structure. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_MAXCMDS │ 1021 │ An invalid value was specified for the maximum number of │ │ │ │ commands parameter. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_BAD_DIRECTORY │ 1139 │ The directory specified for the working directory could │ │ │ │ not be reached. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_MINLR │ 1141 │ An invalid value was specified for the minimum long- │ │ │ │ running time parameter. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_TIMEOUT │ 1142 │ An invalid value was specified for the time-out param- │ │ │ │ eter. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { SEL selROP; // selector for data buffer USHORT rc; // return code cfg_info FAR *pCfgData; // pointer to command array // // Allocate memory for API call. // rc = DosAllocSeg(sizeof(cfg_info),&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pCfgData = (cfg_info FAR *)MAKEP(selROP,0); // load structure with current settings rc = ROPConfigGetInfo( pCfgData ); if (rc){ printf("Error ROPConfigGetInfo return code %d\n",rc); DosFreeSeg(selROP); exit(rc); } pCfgData->MaxLR = 50; pCfgData->MaxCmds = 2; // set the configuration to the new settings rc = ROPConfigSetInfo( pCfgData ); if (rc){ printf("Error ROPConfigSetInfo return code %d\n",rc); }else printf("Config information successfully changed\n"); DosFreeSeg(selROP); exit(rc); } ═══ 8.8. ROPLogGetInfo ═══ ROPLogGetInfo The ROPLogGetInfo function retrieves information about the logging feature of ROP Service. Format #include <ropapi.h> unsigned far pascal ROPLogGetInfo( buf ); char far * buf; Example Return Codes ═══ <hidden> buf ═══ Points to the log_info data structure. See Configuration Information for information about the log_info data structure. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPLogGetInfo is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPLogGetInfo is not large enough to │ │ │ │ contain the log_info structure. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ // // Example for ROPLogGetInfo // #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { SEL selROP; // selector for data buffer USHORT rc; // return code log_info FAR *pLogData; // pointer to command array // // Allocate memory for API call. // rc = DosAllocSeg(sizeof(log_info),&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pLogData = (log_info FAR *)MAKEP(selROP,0); rc = ROPLogGetInfo( pLogData ); if (rc){ printf("Error ROPLogGetInfo return code %d\n",rc); } printf("Maximum allowed file size : %ld\n",pLogData->MaxFileSize); printf("Logging : %s\n",pLogData->Enable?"ON":"OFF"); DosFreeSeg(selROP); exit(rc); } ═══ 8.9. ROPLogSetInfo ═══ ROPLogSetInfo The ROPLogSetInfo function defines parameters for logging commands that ROP Service attempts to execute. Format #include <ropapi.h> unsigned far pascal ROPLogSetInfo(buf); char far * buf; ═══ <hidden> buf ═══ Points to the log_info data structure. See Configuration Information for information about the log_info data structure. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPLogSetInfo is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPLogSetInfo is not large enough to │ │ │ │ contain the log_info structure. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_MAXFILESIZE │ 1140 │ An invalid value was specified for the maximum file size │ │ │ │ parameter. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { SEL selROP; // selector for data buffer USHORT rc; // return code log_info FAR *pLogData; // pointer to command array // // Allocate memory for API call. // rc = DosAllocSeg(sizeof(log_info),&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pLogData = (log_info FAR *)MAKEP(selROP,0); // load structure with current settings rc = ROPLogGetInfo( pLogData ); if (rc){ printf("Error ROPLogGetInfo return code %d\n",rc); DosFreeSeg(selROP); exit(rc); } pLogData->MaxFileSize = 5000; pLogData->Enable = FALSE; // set the configuration to the new settings rc = ROPLogSetInfo( pLogData ); if (rc){ printf("Error ROPLogSetInfo return code %d\n",rc); }else printf("Log information successfully changed\n"); DosFreeSeg(selROP); exit(rc); } ═══ 8.10. ROPStart ═══ ROPStart The ROPStart function starts ROP Service. Format #include <ropapi.h> unsigned far pascal ROPStart( void ) Example Return Codes Remarks ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_ALREADY_STARTED │ 1006 │ ROP Service is already started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INITIALIZING_DS │ 1022 │ Error initializing ROP Service data areas. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INITIALIZING_TIME │ 1023 │ Error initializing ROP Service time monitor. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INITIALIZING_NV │ 1024 │ Error initializing ROP Service NetView monitor. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1025 │ An unexpected error has occurred. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_COULDNOTSTARTROP │ 1083 │ The ROP Service kernel could not be started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_NOSTATUS │ 1084 │ The ROP Service kernel did not respond with status infor- │ │ │ │ mation. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROPBEINGSTARTED │ 1085 │ ROP Service is in the process of being started by another │ │ │ │ process. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Remarks ═══ The ROPStart function does not start the Presentation Manager user interface (PMEUI). If a program is to start the PMEUI, it can launch the ROPPM.EXE program itself. ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; // return code rc = ROPStart(); if (rc){ printf("Error starting Remote Operations Service\n"); }else printf("Remote Operations Service successfully started\n"); exit(rc); } ═══ 8.11. ROPStop ═══ ROPStop The ROPStop function stops ROP Service. Format #include <ropapi.h> unsigned far pascal ROPStop( void ); Example Return Codes ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service was not started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; // return code rc = ROPStop(); if (rc){ printf("Error stopping Remote Operations Service\n"); }else printf("Remote Operations Service successfully stopped\n"); exit(rc); } ═══ 8.12. ROPTblAddCmd ═══ ROPTblAddCmd The ROPTblAddCmd function adds a command to the Command Validation Table. Format #include <ropapi.h> unsigned far pascal ROPTblAddCmd( buf, buflen ) char far * buf; unsigned short buflen; Example Return Codes ═══ <hidden> buf ═══ Points to a buffer containing the name of the command to be added. ═══ <hidden> buflen ═══ Specifies the length of the buffer that is being passed. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPTblAddCmd is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPTblAddCmd is not as large as is │ │ │ │ stated in buflen. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_DUPLICATE_COMMAND │ 1009 │ The command that was specified in the function call │ │ │ │ already exists in the Command Validation Table. The │ │ │ │ function call did not complete. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <string.h> // C string library header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; // return code CHAR pszCommand[260]; // ASCIIZ string containing a command name strcpy(pszCommand,"TYPE"); rc = ROPTblAddCmd(pszCommand,strlen(pszCommand)); if (rc) printf("Error adding command to the Command Validation Table\n"); else printf("Command successfully added to the Command Validation Table\n"); exit(rc); } ═══ 8.13. ROPTblDelCmd ═══ ROPTblDelCmd The ROPTblDelCmd function deletes a command from the Command Validation Table. Format #include <ropapi.h> unsigned far pascal ROPTblDelCmd( buf, buflen ) char far * buf; unsigned short buflen; Example Return Codes ═══ <hidden> buf ═══ Points to a buffer containing the name of the command to be deleted. ═══ <hidden> buflen ═══ Specifies the length of the buffer that is being passed. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPTblDelCmd is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPTblDelCmd is not as large as is │ │ │ │ stated in buflen. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_COMMAND_NOT_FOUND │ 1008 │ The specified command could not be found. The function │ │ │ │ call did not complete. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <string.h> // C string library header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; // return code CHAR pszCommand[260]; // ASCIIZ string containing a command name strcpy(pszCommand,"TYPE"); rc = ROPTblDelCmd(pszCommand,strlen(pszCommand)); if (rc) printf("Error deleting command from the Command Validation Table\n"); else printf("Command successfully deleted from the Command Validation Table\n"); exit(rc); } ═══ 8.14. ROPTblGetInfo ═══ ROPTblGetInfo The ROPTblGetInfo function returns the contents of the Command Validation Table. Format #include <ropapi.h> unsigned far pascal ROPTblGetInfo( buf, buflen, tblswtch, entriesread, totalentries ) char far * buf; unsigned short buflen; unsigned short far * tblswtch; unsigned short far * entriesread; unsigned short far * totalentries; Example Return Codes ═══ <hidden> buf ═══ Points to the area to be filled with the command information. Example ═══ <hidden> buflen ═══ Specifies the length of the buffer that is being passed. ═══ <hidden> tblswitch ═══ Points to the variable where the table exclusive switch is passed. This value is either TRUE or FALSE. ═══ <hidden> entriesread ═══ Points to the variable where the number of entries read is returned. ═══ <hidden> totalentries ═══ Points to the variable where the total number of entries read is available are returned. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUFFER │ 1004 │ The buffer passed to ROPTblGetInfo is not a valid buffer. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INVALID_BUF_SIZE │ 1005 │ The buffer passed to ROPTblGetInfo is not as large as is │ │ │ │ stated in buflen. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; // return code SEL selROP; // selector for data buffer USHORT usbuflen; // length of data buffer BYTE FAR *pbBuf; // pointer to data buffer USHORT usEntriesRead; // number of entries read USHORT usTotalEntries; // total number of entries available USHORT usTblSwitch; // CVT exclusive switch USHORT i; // index for for-loop USHORT usCurrentLen; // length of current command name usbuflen = 1024; rc = DosAllocSeg(usbuflen,&selROP,SEG_NONSHARED); if (rc){ printf("Error allocating needed memory\n"); exit(rc); } pbBuf = MAKEP(selROP,0); rc = ROPTblGetInfo( pbBuf, usbuflen, &usTblSwitch, &usEntriesRead, &usTotalEntries ); if (rc){ printf("Error in ROPTblGetInfo rc = %d\n",rc); }else{ printf("Command Validation Table exclusive option : %s\n",usTblSwitch?"ON":"OFF"); // // Adjust pointer to start off data // pbBuf = MAKEP(selROP,ROP_API_RESERVED); // // loop through data buffer until all of the commands are read // for (i = 0;i < usEntriesRead; i++ ){ // Get length of command usCurrentLen = *((PUSHORT)pbBuf); // move pointer to command pbBuf += sizeof(USHORT); // print command printf("%s\n",(PSZ)pbBuf); // move pointer to next record pbBuf += usCurrentLen+1; } } DosFreeSeg(selROP); exit(rc); } ═══ 8.15. ROPTblSwtch ═══ ROPTblSwtch The ROPTblSwtch function toggles the command validation table between exclusive and inclusive. Format #include <ropapi.h> unsigned far pascal ROPTblSwtch( swtchval ) unsigned short swtchval; Example Return Codes ═══ <hidden> swtchval ═══ Indicates the Boolean condition of the table exclusive switch. ═══ <hidden> Return Codes ═══ ┌──────────────────────────┬───────────┬───────────────────────────────────────────────────────────┐ │ MANIFEST │ VALUE │ MEANING │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_SUCCESS │ 0 │ No errors were encountered. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_PIPE_BROKEN │ 1003 │ The API pipe has been broken. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_ROP_NOT_STARTED │ 1007 │ ROP Service has not been started. │ ├──────────────────────────┼───────────┼───────────────────────────────────────────────────────────┤ │ RERR_INTERNAL_ERROR │ 1027 │ An unexpected error has occurred. │ └──────────────────────────┴───────────┴───────────────────────────────────────────────────────────┘ ═══ <hidden> Example ═══ #define INCL_BASE #include <os2.h> // OS/2 Dos calls definitions #include <stdio.h> // C standard I/O header file #include <stdlib.h> // C standard library header file #include "ropapi.h" // Remote Operations Service API header file VOID main() { USHORT rc; // return code rc = ROPTblSwtch(FALSE); // Turn exclusive switch OFF if (rc) printf("Error setting the Command Validation Table exclusive switch\n"); else printf("Exclusive switch turned off\n"); exit(rc); } ═══ 8.16. API Data Structures ═══ The following topics describe the command information for levels 0 through 2, as well as the configuration information: Command Information (Level 0) Command Information (Level 1) Command Information (Level 2) Configuration Information Logging Information Validation Information ═══ 8.17. Command Information (Level 0) ═══ typedef STRUCT16 _cmd_info_0 { CHAR cmd[CCHMAXPATH]; LONG id; } cmd_info_0; ═══ <hidden> cmd ═══ Is an ASCIIZ string containing the name of an executing command. ═══ <hidden> id ═══ Is the ID of the command. ═══ 8.18. Command Information (Level 1) ═══ typedef STRUCT16_cmd_info_1 { CHAR cmd[CCHMAXPATH]; LONG id; CHAR param[CCHMAXPATH]; ULONG status; CHAR fmtstime[50]; CHAR opid[20]; ULONG realstime; CHAR WSID[9]; BYTE lsn; } cmd_info_1; ═══ <hidden> cmd ═══ Is an ASCIIZ string containing the name of an executing command. ═══ <hidden> id ═══ Is the ID of the command. ═══ <hidden> param ═══ Is an ASCIIZ string containing the parameter list of an executing command. ═══ <hidden> status ═══ Contains the status of the command. The values for the status flag are defined as follows: ┌──────────────┬─────────────┬─────────────────────────────────────────────────────────────────────┐ │ STATUS FLAG │ BIT MASK │ MEANING │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ ACTIVE │ 101 │ The command is presently executing. │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ LONG-RUNNING │ 103 │ The command is still executing, but has taken longer than the long- │ │ │ │ running minimum time. │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ HOLDING │ 104 │ The command has finished executing and ROP Service is holding the │ │ │ │ output until the command is deleted. │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ REMOTE │ 108 │ The command is executing on an ESP. │ └──────────────┴─────────────┴─────────────────────────────────────────────────────────────────────┘ ═══ <hidden> fmtstime ═══ Is an ASCIIZ string containing the formatted starting time. ═══ <hidden> opid ═══ Is an ASCIIZ string containing the NetView operator ID of the user sending the command. ═══ <hidden> realstime ═══ Contains the starting time of the command in seconds since 1970. This field is useful for sorting. ═══ <hidden> WSID ═══ The workstation ID of the workstation where the command is to be processed. ═══ <hidden> lsn ═══ The NetBIOS logical session number. ═══ 8.19. Command Information (Level 2) ═══ typedef STRUCT16_cmd_info_2 { CHAR cmd[CCHMAXPATH]; LONG id; CHAR param[CCHMAXPATH]; ULONG status; CHAR fmtstime[50]; CHAR opid[20]; ULONG realstime; USHORT resultcode; USHORT termcode; CHAR fmtetime[50]; PID sessionid; CHAR corrltr[10]; CHAR outfile[CCHMAXPATH]; CHAR WSID[9]; BYTE lsn } cmd_info_1; ═══ <hidden> cmd ═══ Is an ASCIIZ string containing the name of an executing command. ═══ <hidden> id ═══ Is the ID of the command. ═══ <hidden> param ═══ Is an ASCIIZ string containing the parameter list of an executing command. ═══ <hidden> status ═══ Contains the status of the command. The values for the status flag are defined as follows: ┌──────────────┬─────────────┬─────────────────────────────────────────────────────────────────────┐ │ STATUS FLAG │ BIT MASK │ MEANING │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ ACTIVE │ 101 │ The command is presently executing. │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ LONG-RUNNING │ 103 │ The command is still executing, but has taken longer than the long- │ │ │ │ running minimum time. │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ HOLDING │ 104 │ The command has finished executing and ROP Service is holding the │ │ │ │ output until the command is deleted. │ ├──────────────┼─────────────┼─────────────────────────────────────────────────────────────────────┤ │ REMOTE │ 108 │ The command is executing on an ESP. │ └──────────────┴─────────────┴─────────────────────────────────────────────────────────────────────┘ ═══ <hidden> fmtstime ═══ Is an ASCIIZ string containing the formatted starting time. ═══ <hidden> opid ═══ Is an ASCIIZ string containing the NetView operator ID of the user sending the command. ═══ <hidden> realstime ═══ Contains the starting time of the command in seconds since 1970. This field is useful for sorting. ═══ <hidden> resultcode ═══ Contains the result code with which the command process ended. ═══ <hidden> termcode ═══ Contains the termination code with which the command process ended. ═══ <hidden> fmtetime ═══ Is a ASCIIZ string containing the formatted ending time. ═══ <hidden> sessionid ═══ Is the process ID of the command. ═══ <hidden> corrltr ═══ Is the 10-byte correlator sent by the NetView program. ═══ <hidden> outfile ═══ Is an ASCIIZ string containing the path of the temporary file that is used to capture the output of the command. ═══ <hidden> WSID ═══ The workstation ID of the workstation where the command is to be processed. ═══ <hidden> lsn ═══ The NetBIOS logical session number. ═══ 8.20. Configuration Information ═══ typedef STRUCT16_cfg_info { BYTE Reserved[ROP_API_RESERVED]; CHAR WrkPath[CCHMAXPATH] CHAR NVApplName[81]; CHAR CmdTblName[CCHMAXPATH] USHORT MaxCmds; USHORT MinLR; USHORT Timeout; BOOLEAN16 PMflag; BOOLEAN16 ReplyCodeOnly; BOOLEAN16 UPMcheck; BYTE adap_num; } cfg_info; ═══ <hidden> WrkPath ═══ Is an ASCIIZ string containing the path to the working directory. ═══ <hidden> NVApplName ═══ Is an ASCIIZ string containing the name that ROP Service uses to register with SPA Router. ═══ <hidden> CmdTblName ═══ Is an ASCIIZ string containing the path of the Command Validation Table. ═══ <hidden> MaxCmds ═══ Contains the maximum number of concurrent commands allowed. This can be from 1 to 8. ═══ <hidden> MinLR ═══ Contains the time in seconds that the command is allowed to keep a NetView correlator. ═══ <hidden> Timeout ═══ Contains the time in seconds that the command is allowed to execute. ═══ <hidden> PMflag ═══ Is a flag signaling whether the PMEUI is to be launched. ═══ <hidden> ReplyCodeOnly ═══ Is a flag signaling that ROP Service should reply to the NetView program with only the reply code of the command. ═══ <hidden> UPMcheck ═══ Is a flag signaling that the operator of the NetView account that generated the command is to be validated using the UPM tables. ═══ <hidden> adap_num ═══ Contains the adapter number to be used for NetBIOS communications using ROPS extended service point. This can be from 0 through 255. ═══ 8.21. Logging Information ═══ typedef STRUCT16_log_info { BYTE Reserved[ROP_API_RESERVED]; ULONG MaxFileSize; USHORT Enable; } log_info; ═══ <hidden> MaxFileSize ═══ Is the maximum size in bytes that the log file is allowed to grow. ═══ <hidden> enable ═══ Is a flag signaling whether logging is to be enabled. ═══ 8.22. Validation Information ═══ typedef STRUCT16_valid_info { BYTE Reserved[16]; CHAR Buf[1]; } valid_info; ═══ <hidden> Buf ═══ Has the format LCCC...CCCLCCC...CCCLCCC...CCC... where L Represents the length of the command that follows L CCC...CCC Represents the command whose length is indicated by the preceding L. The command (CCC...CCC) can contain up to 256 characters. ═══ 9. Command Line Interface (CLI) Executable Components ═══ Command Line Interface (CLI) is a group of four executable components that provides SNA and NetBIOS subsystem management functions through the command line. Through the use of Remote Operations Service (ROPS), CLI gives the NetView operator the ability to monitor communications at an OS/2 workstation. Related Topics: CLI Functional Overview CMDLC Component CMDLC Syntax CMLINKS Component CMLINKS Syntax CMTPS Component CMTPS Syntax CMNETB Component CMNETB Syntax ═══ 9.1. CLI Functional Overview ═══ The following CLI executable components enable you to do the following: CMDLC View and control data link controls (DLCs) CMLINKS View and control SNA Logical Links CMTPS View and control transaction programs CMNETB View NetBIOS names and sessions information. The CLI components and their relation to the overall system are shown in the following diagram: NV - NetView o Commands are sent in Network Management Vector Transport (NMVT) packets to the service point by the Service Point Command Service. OS/2 CM - OS/2 Communication Manager o Receives the NMVT request and places it in the appropriate queue. SPA RTR - Service Point Application Router o Processes the NMVT, passes the command string to the application, and packages the replies into NMVTs for returning to NetView. ROPS Appl - Remote Operations Service Application o Executes commands destined for the service point and returns output from the command to SPA Router. Commands can be executed on an extended service point workstation when an extended service point workstation ID (WSID) is specified in the NMVT. CLI - Command Line Interface o CMDLC - processes arguments passed and displays resulting DLC information. o CMLINKS - processes arguments passed and displays resulting Logical Links information. o CMTPS - processes arguments passed and displays resulting Transaction Programs information. o CMNETB - processes arguments passed and displays resulting NETBIOS Names and Sessions information. ESP - Extended Service Point The following table lists the files copied to the \CMLIB directory by the installation process. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Command Line Interface (CLI) Files │ ├────────────────────────┬─────────────────────────────────────────────────────────────────────────┤ │ FILE NAME │ DESCRIPTION │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CMLINKS.EXE │ CMLINKS command line executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CMDLC.EXE │ CMDLC command line executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CMTPS.EXE │ CMTPS command line executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CMNETB.EXE │ CMNETB command line executable file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CLI.MSG │ CLI message file │ ├────────────────────────┼─────────────────────────────────────────────────────────────────────────┤ │ CLIH.MSG │ CLI command line message help file │ └────────────────────────┴─────────────────────────────────────────────────────────────────────────┘ ═══ 9.1.1. CMDLC Component ═══ The function of the CMDLC component is to provide DLC information and to allow the status of a DLC to be modified. CMDLC actions and output are shown in Output from from CMDLC. Syntax: CMDLC [ action ] [ parameter ] Actions Parameters ------- ------------------- A [## | DLC name | *] Activate the specified DLC(s) D [## | DLC name | *] Deactivate the specified DLC(s) K [keylock | *] Define or reset the keylock value ? Toggle command syntax information ## DLC Name # Status -- -------- - --------- Output from from CMDLC ═══ 9.1.1.1. CMDLC Syntax ═══ The syntax diagram for the CMDLC command is as follows: ┌──────────────────────────┐ │ >>──CMDLC───┬────────────────────────┬┴───────────────────────────────────────────────────────────>< ├─┬─A────┬──┬─##───────┬─┤ │ └─D────┘ ├─DLC name─┤ │ │ └─*────────┘ │ ├─K─────┬─keylock─┬──────┤ │ └─*───────┘ │ └─?──────────────────────┘ CMDLC is able to get information about the DLCs defined on a given workstation through the APPC API. Information including DLC name, adapter number, and adapter status is accessed and displayed through the DISPLAY verb. Numerical correlators are listed for each entry. Return Codes: Errors reported during CMDLC processing include primary and secondary return codes. See the System Management Programming Reference for recommended actions for the return codes. ═══ <hidden> A ═══ Activates a specified DLC. The DLC can be referenced by the correlator (## field), DLC name, or asterisk (*) designating activation of all DLCs. Activation of the specified DLCs is requested through the ACTIVATE_DLC verb. ═══ <hidden> D ═══ Deactivates a specified DLC. The DLC can be referenced in the same way as the activate action. Deactivation of the specified DLCs is requested through the DEACTIVATE_DLC verb. ═══ <hidden> K ═══ Sets or resets an internal key name. If the keylock option is not used to lock the current communications configuration, the key name value has no effect. However, if the configuration is locked, the key name set here must match the one used by the keylock option. The functions requiring a match during a locked state are activation and deactivation of DLCs. Enter an asterisk (*) to reset the key name to the default value, which is 8 ASCII blanks. Because execution through ROPS does not allow interaction, this value is not retained between multiple RUNCMDs. Therefore, if a key name is needed, it must be supplied on all calls. ═══ <hidden> ? ═══ Toggles syntax information describing the valid actions. No parameters are required. ═══ 9.1.2. CMLINKS Component ═══ The function of the CMLINKS component is to provide logical links information and to allow for the modification of a link's status. CMLINKS actions and output are shown in Output from CMLINKS. Syntax: CMLINKS [ action ] [ parameter ] Actions Parameters ------- ------------------- A [Link name | *] Activate specified link(s) S [Link name | *] Soft deactivate specified link(s) H [Link name | *] Hard deactivate specified link(s) L [Link name | *] Toggle the link lock status K [keylock | *] Define or reset the keylock value ? Toggle command syntax information Link DLC Partner Name Name # FQName Type Sess State -------- -------- - ----------------- ----- ---- --------------- Output from CMLINKS ═══ 9.1.2.1. CMLINKS Syntax ═══ The syntax diagram for the CMLINKS command is as follows: ┌───────────────────────────┐ │ >>──CMLINKS───┬─────────────────────────┬┴────────────────────────────────────────────────────────>< ├─┬─A────┬──┬─link name─┬─┤ │ ├─S────┤ └─*─────────┘ │ │ ├─H────┤ │ │ └─L────┘ │ ├─K─────┬─keylock─┬───────┤ │ └─*───────┘ │ └─?───────────────────────┘ CMLINKS is able to get information about the logical links defined on a given workstation through the APPC API. Information including link name, DLC name, adapter number, partner fully-qualified name, partner type, number of sessions, and link state is accessed and displayed through the DISPLAY verb. Return Codes: Errors reported during CMLINKS processing include primary and secondary return codes. See the System Management Programming Reference for recommended actions for the return codes. ═══ <hidden> A ═══ Activates a specified logical link. The link can be referenced by the link name or by an asterisk (*), designating activation of all links. Activation of the specified logical links is requested through the ACTIVATE_LOGICAL_LINKS verb. ═══ <hidden> S ═══ Soft deactivates a specified logical link. The link can be referenced in the same way as the activate action. Soft deactivation of the specified links is requested through the DEACTIVATE_LOGICAL_LINKS verb with the deactivation type set to SOFT. ═══ <hidden> H ═══ Hard deactivates a specified logical link. The link can be referenced in the same way as the activate action. Hard deactivation of the specified links is requested through the DEACTIVATE_LOGICAL_LINKS verb with the deactivation type set to HARD. The ability to reset links is sometimes possible by combining hard deactivate and activate requests. ═══ <hidden> L ═══ Enables you to toggle the lock state of any link. When an activate or deactivate command is issued for all links, all links that are not locked will respond to the command. When a command is issued for a specific locked link, the lock status will not prevent the locked link from responding to the command. ═══ <hidden> K ═══ Sets or resets an internal key name. If the keylock option is not used to lock the current communications configuration, the key name value has no effect. However, if the configuration is locked, the key name set here must match the one used by the keylock option. ═══ <hidden> ? ═══ Toggles syntax information describing the valid actions. No parameters are required. ═══ 9.1.3. CMTPS Component ═══ The function of the CMTPS component is to provide transaction program (TP) information and to allow for the modification of TP and attach manager status. There are two panels of output provided by this component. The general TP information panel is shown in Output from CMTPS: General TP Information and the TP details panel is shown in Output from CMTPS: TP Instance Details. Attach Manager is: Inactive Syntax: CMTPS [ action ] [ parameter ] Actions Parameters ------- ------------------- S Start Attach Manager D [# | *] Deactivate specified TP(s) L [# | 0] List details for the specified TP(s) K [keylock | *] Define or reset the keylock value ? Toggle command syntax information # #TP Transaction Program name --- --- ------------------------------------------------------------- Output from CMTPS: General TP Information Attach Manager is: Active Syntax: CMTPS [ action ] [ parameter ] Actions Parameters ------- ------------------- S Stop Attach Manager D [# | *] Deactivate specified TP(s) L [# | 0] List details for the specified TP(s) K [keylock | *] Define or reset the keylock value ? Toggle command syntax information TP: # TP ID Initiated LUW Instance LU Alias # conv --- ---------------- --------- ------------ -------- ------ Output from CMTPS: TP Instance Details ═══ 9.1.3.1. CMTPS Syntax ═══ The syntax diagram for the CMTPS command is as follows: ┌─────────────────────┐ │ >>──CMTPS───┬───────────────────┬┴────────────────────────────────────────────────────────────────>< ├─S─────────────────┤ ├─D─────┬─#─┬───────┤ │ └─*─┘ │ ├─L─────┬─#─┬───────┤ │ └─0─┘ │ ├─K─────┬─keylock─┬─┤ │ └─*───────┘ │ └─?─────────────────┘ CMTPS is able to get information about the TPs running on a given workstation through the APPC API. Information including number of instances of a TP, TP name, TP ID, where initiated, fully qualified LU name, LU alias, and number of conversations is accessed and displayed through the DISPLAY verb. TP names and the number of TP instances are shown on the general TP information panel while the other information is shown on the TP details panel. Numerical correlators are listed for each entry. Return Codes: Errors reported during CMTPS processing include primary and secondary return codes. See the System Management Programming Reference for recommended actions for the return codes. ═══ <hidden> S ═══ Starts or stops the attach manager. Start and stop requests use the START_AM and STOP_AM verbs. This action requires no parameters. ═══ <hidden> D ═══ Deactivates a specified TP group or TP instance. If the current panel is the general TP information panel, all instances of the specified TP (#) will be deleted. If the current panel is the TP details panel, the specified instance (#) will be deleted. The asterisk (*) can also be used to delete all entries on the current panel. Deletion of the specified TPs is requested through the DELETE_TP verb. ═══ <hidden> L ═══ Lists the details about a specific TP group. The group is referenced by the numerical correlator on the far left of a TP entry. Only the group correlators are used for this action. If a parameter of 0 is supplied, the general TP information panel is displayed. ═══ <hidden> K ═══ Sets or resets an internal key name. If the keylock option is not used to lock the current communications configuration, the key name value has no effect. However, if the configuration is locked, the key name set here must match the one used by the keylock option. The functions requiring a match during a locked state are start and stop of the AM and deletion of TPs. ═══ <hidden> ? ═══ Toggles syntax information describing the valid actions. No parameters are required. ═══ 9.1.4. CMNETB Component ═══ The function of the CMNETB component is to provide NetBIOS names and sessions information. There are two panels of output provided by this component. The NetBIOS names information panel is shown in Output from CMNETB: NetBIOS Names Information and the NetBIOS session information panel is shown in Output from CMNETB: NetBIOS Sessions Information. Syntax: CMNETB [ action ] [ parameter ] Actions Parameters ------- ------------------- S View NCB session info N View NCB names info A [adapter #] Choose adapter number (currently 0) ? Toggle command syntax information Name NETBIOS Name NCB_NUM Type Status ------------------ --------- -------- ------------------------------ Output from CMNETB: NetBIOS Names Information Syntax: CMNETB [ action ] [ parameter ] Actions Parameters ------- ------------------- S View NCB sessions info N View NCB names info A [adapter #] Choose adapter number (currently 0) ? Toggle command syntax information lsn session state local name remote name ----- --------------------- ------------------ ------------------ Output from CMNETB: NetBIOS Sessions Information ═══ 9.1.4.1. CMNETB Syntax ═══ The syntax diagram for the CMNETB command is as follows: ┌───────────────────┐ │ >>──CMNETB───┬─────────────────┬┴─────────────────────────────────────────────────────────────────>< ├─S───────────────┤ ├─N───────────────┤ ├─A─────adapter #─┤ └─?───────────────┘ CMNETB is able to get information about the NetBIOS names and sessions defined on a given workstation through the use of the NetBIOS API. Information including NetBIOS name, NCB_NUM, name type, and name status is accessed and displayed through the NCB_STATUS verb on the NetBIOS names panel. Information including local session number, session state, local name, and remote name are accessed and displayed through the NCB_SESSION_STATUS verb on the NetBIOS sessions panel. Note: The characters that cannot be displayed are show as periods ('.'). A character that cannot be displayed is one that is not over 0x20 in the ASCII character set. Return Codes: Errors reported during CMNETB processing include the NetBIOS return codes. See the IBM LAN Technical Reference Manual for recommended actions for the return codes. ═══ <hidden> S ═══ Views NetBIOS sessions information. Along with the status calls already mentioned, NCB_RESET is used to allocate resources for getting the information. This action requires no parameters. ═══ <hidden> N ═══ Views NetBIOS names information. Along with the status calls already mentioned, NCB_RESET is used to allocate resources for getting the information. This action requires no parameters. ═══ <hidden> A ═══ Specifies the adapter to query when getting the NetBIOS information. The value can range from 0 to 255 and the default is 0. This value is used as the local area network adapter (LANA) value for all NetBIOS calls made. ═══ <hidden> ? ═══ Toggles syntax information describing the valid actions. No parameters are required. Note: Undisplayable characters are shown as periods ('.'). An undisplayable character is one which is not between 0x20 and 0x80 in the ASCII character set. ═══ 9.1.5. Migration ═══ The CLI components were created for release with Communications Manager 1.1. They should not be used on previous versions of Communications Manager due to dependencies on the APPC API at the 1.1 level. ═══ 10. SPA Router Trace Formats ═══ Traces can be generated to debug and identify problems with applications that call any of the function calls of SPA Router. For information about using the trace facility of Communications Manager, refer to Problem Determination Guide. SPA Router can generate two main types of traces. The first type of trace is a trace of all SPA Router function calls. This type of trace is controlled by the /TRACEAPI option of the TRACE command. The second type of trace is a trace of all the data received and transmitted by SPA Router; that is, a trace of the NMVTs. This type of trace is controlled by the /TRACEDATA option of the TRACE command. This section includes sample traces and an explanation of how to read the trace information. Trace Fields for API Traces Trace Fields for NMVT Traces Examples ═══ <hidden> Examples ═══ The following are several trace examples that were generated by selecting both the /TRACEAPI option and the /TRACEDATA option of SPA Router. API REQUEST SPAROUTR C=8 Open PID=18 TID=1 15:40:00:50 41524233 01036000 00000000 00000041 <ARB3..-........A> 4C455254 4D475200 00000000 00000000 <LERTMGR.........> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> API RETURN SPAROUTR C=8 Open PID=18 TID=1 OK 15:40:00:53 41524233 01036000 00000000 00000041 <ARB3..-........A> 4C455254 4D475200 00000000 00000000 <LERTMGR.........> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> RECEIVENMVT SPAROUTR OK 15:42:27:59 4E657476 69657720 4E4D5654 2066726F <Netview NMVT fro> 6D205350 43492051 2C205052 49443D30 <m SPCI Q, PRID=0> 78303030 31 <x0001 > ACCEPTNMVT SPAROUTR applicname=ALERTMGR OK 15:42:27:59 50524944 3D307830 3030312C 20436C65 <PRID=0x0001, Cle> 61726564 204E4D56 54206172 72697661 <ared NMVT arriva> 6C207365 6D617068 6F726520 30783143 <l semaphore 0x1C> 44463030 30302C20 4E4D5654 20776169 <DF0000, NMVT wai> 74696E67 3D310A <ting=1. > RECEIVENMVT SPAROUTR OK 15:43:35:15 4E657476 69657720 4E4D5654 2066726F <Netview NMVT fro> 6D205350 43492051 2C205052 49443D30 <m SPCI Q, PRID=0> 78303030 32 <x0002 > ACCEPTNMVT SPAROUTR applicname=ALERTMGR OK 15:43:35:15 50524944 3D307830 3030322C 20436C65 <PRID=0x0002, Cle> 61726564 204E4D56 54206172 72697661 <ared NMVT arriva> 6C207365 6D617068 6F726520 30783143 <l semaphore 0x1C> 44463030 30302C20 4E4D5654 20776169 <DF0000, NMVT wai> 74696E67 3D320A <ting=2. > API REQUEST SPAROUTR C=9 RCmdRcv PID=18 TID=1 15:43:57:21 41524233 03036000 00000000 00000041 <ARB3..-........A> 4C455254 4D475200 00000000 00000000 <LERTMGR.........> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> API RETURN SPAROUTR C=9 RCmdRcv PID=18 TID=1 OK 15:43:57:21 41524233 03036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475200 00000000 00000000 <LERTMGR.........> 00000000 00000000 00140000 EF1C0001 <................> 61000000 00000000 00000000 00000000 <a...............> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> API REQUEST SPAROUTR C=A RCmdRep PID=18 TID=1 15:45:15:43 41524233 02036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000200 590000BF 1C140000 EF1C0001 <....Y...........> 61000000 00000000 00016100 00000000 <a.........a.....> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> SENDNMVT SPAROUTR applicname=ALERTMGR OK 15:45:15:46 41038D00 00000180 00160061 12440401 <A..........a.D..> 00010610 00000001 06110000 02000043 <...............C> 13001631 C1D3C5D9 E3D4C7D9 40E2C8D6 <...1ALERTMGR SHO> E640E2E3 C1E3E4E2 2931C1D3 D340C4C5 <W STATUS)1ALL DE> E5C9C3C5 E240D9E4 D5D5C9D5 C740C6C9 <VICES RUNNING FI> D5C55E40 D5D640D5 C5E640C1 D3C5D9E3 <NE^ NO NEW ALERT> E2 <S > API RETURN SPAROUTR C=A RCmdRep PID=18 TID=1 OK 15:45:15:46 41524233 02036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000200 590000BF 1C140000 EF1C0001 <....Y...........> 61000000 00000000 00016100 00000000 <a.........a.....> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> API REQUEST SPAROUTR C=B RCmdRcv PID=18 TID=1 15:45:26:75 41524233 03036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000200 590000BF 1C140000 EF1C0001 <....Y...........> 61000000 00000000 00016100 00000000 <a.........a.....> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> API RETURN SPAROUTR C=B RCmdRcv PID=18 TID=1 OK 15:45:26:78 41524233 03036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000200 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00016100 00000000 <a.........a.....> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> API REQUEST SPAROUTR C=C RCmdRep PID=18 TID=1 15:48:31:37 41524233 02036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000200 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00026100 00000000 <a.........a.....> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> SENDNMVT SPAROUTR applicname=ALERTMGR OK 15:48:31:40 41038D00 00000280 00160061 12440401 <A..........a.D..> 00010610 00000001 06110000 0200005C <...............\> 13002031 C1D3C5D9 E3D4C7D9 40E4D7C4 <.. 1ALERTMGR UPD> C1E3C540 D3C5E5C5 D37EC3D9 C9E3C9C3 <ATE LEVEL=CRITIC> C1D33831 E3F1E3D6 D5E8C340 E3E8D7C5 <AL81T1TONYC TYPE> 7EC2D9C9 C4C7C540 C861E640 C3D9C9E3 <=BRIDGE HaW CRIT> C9C3C1D3 40C6C1C9 D3E4D9C5 40C3D6C4 <ICAL FAILURE COD> C57EF7F1 F2F4F5F6 F0F0 <E=71245600 > API RETURN SPAROUTR C=C RCmdRep PID=18 TID=1 OK 15:48:31:40 41524233 02036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000200 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00026100 00000000 <a.........a.....> 00000000 00000000 00000000 00000000 <................> 00000000 00000000 00000000 0000DF1C <................> API REQUEST SPAROUTR C=D AppEnum PID=18 TID=1 15:49:20:53 API RETURN SPAROUTR C=D AppEnum PID=18 TID=1 OK 15:49:20:53 414C4552 544D4752 00504C0F 27000000 <ALERTMGR.PL.'...> 0008000F 2800070A C607 <....(...F. > API REQUEST SPAROUTR C=E CfgGetI PID=18 TID=1 15:49:33:68 API RETURN SPAROUTR C=E CfgGetI PID=18 TID=1 OK 15:49:33:68 80002000 25000F00 02000000 <.. .%....... > API REQUEST SPAROUTR C=F USolSnd PID=18 TID=1 15:51:14:65 41524233 0A036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000100 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00026100 00000000 <a.........a.....> 0000004A 4F484E44 4F452000 00000000 <...JOHNDOE .....> 00000000 00000000 00000000 0000DF1C <................> SENDNMVT SPAROUTR applicname=ALERTMGR OK 15:51:14:68 41038D00 00000000 0010006F 0C060A50 <A..........o...P> D1D6C8D5 C4D6C540 003D1300 3931E3D6 <JOHNDOE .=..91TO> D640D4C1 D5E840C6 C1C9D3E4 D9C5E240 <O MANY FAILURES > C9D540C9 E2C4D540 D3C9D5C5 40F540E3 <IN ISDN LINE 5 T> D640D7C8 D6C5D5C9 E740C6D9 D6D440C1 <O PHOENIX FROM A> E4E2E3C9 D5 <USTIN > API RETURN SPAROUTR C=F USolSnd PID=18 TID=1 OK 15:51:14:68 41524233 0A036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000100 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00026100 00000000 <a.........a.....> 0000004A 4F484E44 4F452000 00000000 <...JOHNDOE .....> 00000000 00000000 00000000 0000DF1C <................> API REQUEST SPAROUTR C=10 Close PID=18 TID=1 15:51:26:03 41524233 04036061 00000000 00000041 <ARB3..-a.......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000100 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00026100 00000000 <a.........a.....> 0000594A 4F484E44 4F452000 00000000 <..YJOHNDOE .....> 00000000 00000000 00000000 0000DF1C <................> API RETURN SPAROUTR C=10 Close PID=18 TID=1 OK 15:51:26:06 41524233 04036061 60000000 00000041 <ARB3..-a-......A> 4C455254 4D475242 00000000 00000000 <LERTMGRB........> 00000100 590000BF 1C1E0000 EF1C0002 <....Y...........> 61000000 00000000 00026100 00000000 <a.........a.....> 0000594A 4F484E44 4F452000 00000000 <..YJOHNDOE .....> 00000000 00000000 00000000 0000DF1C <................> API REQUEST SPAROUTR C=11 CfgGetI PID=19 TID=1 15:51:51:43 API RETURN SPAROUTR C=11 CfgGetI PID=19 TID=1 OK 15:51:51:43 80002000 25000F00 02000000 <.. .%....... > ═══ <hidden> Trace Fields for API Traces ═══ Each trace record contains various fields. The content of the fields depends on whether the trace is a trace of the SPA Router function calls (the /TRACEAPI option was used) or a trace of the NMVTs (the /TRACEDATA option was used). For every SPA Router function call, two trace records are generated. The first trace record is generated when the function call is first received. The second trace record is generated when the function call has been completed and is ready to be returned to the caller. The first record has a header tag of API REQUEST. The second record has a header tag of API RETURN. Each trace record includes the following information. The values in parentheses following the descriptions are the values of the fields as shown in the first set of example traces. o Either API REQUEST or API RETURN, indicating whether the record is an entry record or an exit record, respectively. (API REQUEST) o The identification of the application that created the record. (SPAROUTR) o The count number, displayed in hex decimal. (C=8) o The tag that identifies the function call generating the trace. (Open) o The OS/2 process and thread ID from which the function call originated, displayed in hex decimal. (PID=18 TID=1) o The time the function call was received for an API REQUEST record and the time the function call was completed for an API RETURN record. The time is displayed in hour:minute:seconds:milliseconds format (15:40:00:50). o For API RETURN records, the status of the function call. OK indicates that the function call completed normally. If the function call did not complete properly, NOK is displayed. o The body of the trace record. If the function call is an SPCF function call, the body shows the ARB structure that was passed when the function call was called. In the first trace example, the API REQUEST example, the body is 96 bytes long for the SPCF Open function call for name ALERTMGR. The body of the API RETURN example record shows the semaphore address that was passed from SPA Router to the application. This address indicates whether any commands have been received from the NetView program for the application name. The address in the second example is DF1C:0000 (indicated in the last 4 bytes of the ARB returned to the caller). If the function call is a SPA Router management or configuration function call (such as RTRApplEnum and RTRConfigGetInfo), the body shows the primary data structure used by the call (since these calls do not use ARBs). For example, for the RTRApplEnum() function call (for which the tag is AppEnum), the body shows the application structure information that is returned by SPA Router. For the RTRConfigGetInfo() function call (for which the tag is CfgGetI), the body shows the configuration structure returned by SPA Router. ═══ <hidden> Trace Fields for NMVT Traces ═══ Each trace record contains various fields. The content of the fields depends on whether the trace is a trace of the SPA Router function calls (the /TRACEAPI option was used) or a trace of the NMVTs (the /TRACEDATA option was used). For tracing data (the NMVTs for SPA Router), there are the following three types of trace records, and a table that describes trace tags: RECEIVENMVT ACCEPTNMVT SENDNMVT Table of Trace Tags ═══ <hidden> The RECEIVENMVT Trace Record ═══ The RECEIVENMVT record is created when an NMVT is received by SPA Router. The body of this record shows the procedure-related identifier (PRID) value of the NMVT received. This PRID value is incremented by a value of 1 every time the NetView program sends an NMVT. For example, the first RECEIVENMVT record in the sample records shows a PRID value of 0x0001 and the second RECEIVENMVT record in the sample records shows a PRID value of 0x0002. ═══ <hidden> The ACCEPTNMVT Trace Record ═══ The ACCEPTNMVT record shows whether a previous RECEIVENMVT NMVT was actually accepted by SPA Router. An NMVT is accepted if the target application name has been registered with SPA Router, the receive queue for the name has room for the application name, and the NMVT had the SNA-prescribed format. The trace record for an ACCEPTNMVT shows other useful information as well. Referring to the sample traces, the first ACCEPTNMVT was accepted for the target application name ALERTMGR, and it had a PRID value of 0x0001. The RAM semaphore cleared for the application notification of the NMVT arrival had an address of 0x1CDF0000, and at that time the application name had one NMVT waiting, including the new one received. The trace record also shows the time at which the NMVT was accepted, displayed in hour:minutes:seconds:milliseconds format. ═══ <hidden> The SENDNMVT Trace Record ═══ The SENDNMVT record is added for every NMVT that is sent by SPA Router. It can originate when an application name issues some form of send API function call. It can also originate when SPA Router itself has to send an NMVT (for example, when the receive queue for an application name is full and SPA Router receives a new NMVT from the NetView program for the application name). If the function call was sent by an application and not by SPA Router, then applicname=applname is displayed, where applname is the name of the application sending the function call. If the function call was sent by SPA Router, then applicname=applname is not displayed. In either case, the complete NMVT being sent to the NetView program is displayed in the body of the trace record. In the trace examples, the first SENDNMVT record trace is for the application name ALERTMGR at time 15:45:15:46. This trace record was created when ALERTMGR issued the RunCommand reply function call at time 15:45:15:43. This first example of SENDNMVT shows that ALERTMGR replied from the buffer and sent out the messages ALERTMGR SHOW STATUS, ALL DEVICES RUNNING FINE, and NO NEW ALERTS. (The sample program for ALERTMGR always echoes the received command first and then adds the replies.) Note that one reply request by an application generates the following three records in the trace file in the order shown: API REQUEST RCmdRep, SENDNMVT applicname=ALERTMGR, and API RETURN RCmdRep. ═══ <hidden> Table of Trace Tags ═══ Trace Tags lists the tags used in the header of the trace record for each function call and the information shown in the trace body for each tag. ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Trace Tags │ ├───────────────────┬───────────────────┬──────────────────────────────────────────────────────────┤ │ TRACE TAG │ TRACE BODY │ MEANING │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ Open │ ARB │ SPCF Open; Request code 0x0301 │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ OpenQdp │ ARB │ SPCF Open with Q depth; Request code 0x0311 │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ Close │ ARB │ SPCF Close; Request code 0x0304 │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ RCmdRcv │ ARB │ Receive RunCmd; Request code 0x0303 │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ ACmdRcv │ ARB │ Receive any command; Request code 0x0309 │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ RCmdRep │ ARB │ Send RunCmd reply; Request code 0x0302 │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ USolSnd │ ARB │ Send unsolicited message; Request code 0x030A │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ ACmdRep │ ARB │ Send any cmd reply; Request code 0x030B │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ ErSense │ ARB │ Send error sense; Request code 0x030C │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ USoNMVT │ ARB │ Send unsolicited NMVT; Request code 0x030D │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ AppEnum │ appl_info │ RTRApplEnum │ │ │ returned │ │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ AppGetI │ appl_info │ RTRApplGetInfo │ │ │ returned │ │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ AppDel │ none │ RTRApplDel │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ CfgGetI │ config_info │ RTRConfigGetInfo │ │ │ returned │ │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ CfgSetI │ config_info set │ RTRConfigSetInfo │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ Start │ config_info │ RTRStart │ │ │ passed │ │ ├───────────────────┼───────────────────┼──────────────────────────────────────────────────────────┤ │ StopRTR │ none │ RTRShutdown │ └───────────────────┴───────────────────┴──────────────────────────────────────────────────────────┘ ═══ 11. Troubleshooting ═══ This section contains information that you may find useful when trying to resolve problems. Select one of the following topics to find out about a potential problem area: Starting Communications Manager, SPA Router, and ROP Service Sending Commands from the NetView Program Starting Application Programs Remote Operations Service Traps Running Persistent Applications Using Extended Service Point ═══ 11.1. Starting Communications Manager, SPA Router, and ROP Service ═══ SPA Router must be started before ROP Service is started. To start the SPA Router and ROP Service when your workstation is started, include the following in your start-up command (STARTUP.CMD) file: /* IMBED CLIST IN STARTUP.CMD FILE */ 'START /N RTR' '@ECHO OFF' DO UNTIL RC = 0 'RTR CONFIG >NUL 2>&1' END '@ECHO ON' 'START /N ROPPM /FULLSIZE' 'EXIT' If both SPA Router and ROP Service are running, but you stop and then restart SPA Router, ROP Service cannot communicate with the NetView program even though ROP Service is still running. This is because when you stopped SPA Router, the application name for ROP Service was deleted (it was no longer registered). To reregister the application name for ROP Service, stop ROP Service and start it again. ═══ 11.2. Sending Commands from the NetView Program ═══ When you send a NetView command to SPA Router for an application that you know is registered with SPA Router, but you receive the message that the application is not registered with SPA Router, check that the host code page configuration parameter set for SPA Router matches the EBCDIC code page of the NetView program. ═══ 11.3. Starting Application Programs ═══ Some application programs do not run properly when started from a child process (that is, through ROP Service directly). If you experience difficulties running an application, try starting it with its own session by using the START /I /C command and specifying the application name as a parameter. ═══ 11.4. Remote Operations Service Traps ═══ A trap pop-up is not displayed when a trap occurs in ROP Service itself. Hard error and exception processing are disabled through a call to DosError. Processes started by ROP Service may display trap pop-ups. When this happens, other processes may continue-ROP Service can still process other RUNCMDs. Someone working at the workstation where the pop-up is displayed would have to respond to the pop-up before continuing. ROP Service never sends pop-ups to the NetView console. ═══ 11.5. Running Persistent Applications ═══ ROP Service is not intended to run persistent applications (that is, applications that will be running for an extended period). If you want to start a service or a persistent application, use the START /I /C command. Using the START /I /C command will not tie up ROP Service resources and will allow the service or application to run unsupervised by ROP Service. ═══ 11.6. Using Extended Service Point ═══ When setting the workstation identifier (WSID) for an extended service point workstation, the WSID is case sensitive and it must be unique. If you are having trouble using the extended service point function, ensure that you have allocated sufficient NetBIOS resources for your applications. ROP Service and the extended service point function each require 8 network control blocks (NCBs), 8 logical session names (LSNs), and one NetBIOS name. ═══ <hidden> ═══ ARB LENGTHs of 90 and 67 are also supported for the purpose of compatibility with the NetView/PC program. ═══ <hidden> ═══ Intel** word format swaps bytes: low byte, high byte. Host word format keeps bytes in order: high byte, low byte. 
(.txt)