Networking and Data Communications Library SNAX/HLS Configuration and Control Manual Abstract SNAX/HLS provides a general, high-level interface for application programs to communicate with intelligent SNA devices and software products. This manual provides information on setting up and operating SNAX/HLS. Part Number 104705 Edition Second Published December 1994 Product Version SNAX/HLS D30 Release ID Supported Releases D30 This manual supports D30.
Document History Edition Part Number Product Version Earliest Supported Release Published First Update 1 Second 063743 068530 104705 SNAX/HLS C30.06 SNAX/HLS D10 SNAX/HLS D30 C30.06 D10 D30 December 1991 February 1993 December 1994 New editions incorporate any updates issued since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .
New and Changed Information The changes to the SNAX/HLS Configuration and Control Manual in this version, part number 104705, override the text in the manual with the previous part number, 068530. The majority of the changes are changes to style and wording. However, major changes are mentioned in this section along with the chapter references. Changes are noted with change bars. The changes are as follows: Guardian 90 is now the Tandem NonStop Kernel. Section 4 is now “Using the HLSRDT Utility.
New and Changed Information (This page left intentionally blank) iv 104705 Tandem Computers Incorporated
Contents About This Manual xiii Notation Conventions Section 1 xv Product Overview Introduction 1-1 SNAX/HLS in Relation to Other SNA Products 1-2 SNAX/HLS and the Tandem SNA Access Method SNALU Interface SNA Features Supported by SNAX/HLS 1-4 Data Presentation and Formatting Requirements 1-4 Personnel Required for SNAX/HLS Development 1-4 Principal Parts of SNAX/HLS 1-5 1-3 The Application Interface 1-5 Verbs 1-5 Replies to Verbs 1-5 Delivery of Verbs and Replies 1-5 Verb Names 1-6 Self-Configuring
Contents Step 3. Planning Session BINDs 2-6 FM and TS Profile Selection 2-7 Primary and Secondary FM Usage 2-7 TS Usage 2-13 PS Profile 2-14 Primary LU Network Name 2-15 User Data 2-15 Step 4. Planning the Application Environment 2-15 Run-Time LU and PROFILE Naming 2-15 Using SNAX/HLS as a Pathway Server 2-16 Selecting PROFILE Attributes 2-20 NonStop Programming Considerations 2-23 Step 5.
Contents Modifying the Message File (HLSMSGS) 3-6 Modifying Retry Action Codes 3-7 Format of HLSMSGS File 3-7 Using HLSRUN to Configure Pathway 3-9 Invoking the HLSRUN Macro 3-9 Using HLSCMI to Create a SNAX/XF Loopback Environment Section 4 3-12 Using the HLSRDT Utility Introduction 4-1 Running HLSRDT 4-1 Preparing Commands 4-3 Comments 4-3 Multiple Commands 4-3 Empty Commands 4-3 Case Sensitivity 4-3 Blanks 4-3 Syntactic Elements 4-3 Keywords 4-3 Strings 4-3 Numbers 4-3 Command Dictionary 4-4 ADD
Contents SHOW Command 4-24 SYSTEM Command 4-26 VERSION Command 4-27 VOLUME Command 4-28 Objects and Attributes 4-29 Object and Attribute Summary PROFILE Attributes 4-29 BIND Attributes 4-37 INIT Attributes 4-45 4-29 Using HLSRDT Examples 4-46 Section 5 Operating SNAX/HLS Starting SNAX/HLS 5-1 Format of RUN HLSOBJ Command SNAX/HLS Configuration Parameters 5-2 5-4 Examples of SNAX/HLS Startup 5-9 Assumptions About the Examples 5-9 Example 1 Startup Parameters in RUN Command 5-10 Example 2 Startup Para
Contents CMDSYS Command 6-13 CMDVOL Command 6-14 ENV Command 6-15 EXIT Command 6-16 FC Command 6-17 FILES Command 6-18 HELP Command 6-20 INFO Command 6-21 LOG Command 6-30 OBEY Command 6-31 OBEYSYS Command 6-32 OBEYVOL Command 6-33 OPEN Command 6-34 PEEK Command 6-35 QMSG Command 6-43 STATUS Command 6-44 SYSTEM Command 6-60 TRACE Command 6-61 VERSION Command 6-64 VOLUME Command 6-65 Section 7 Interpreting SNA Protocol Response Protocols Bracket Initiation 7-1 7-1 Temporary UNBIND 7-2 Treatment of Flo
Contents Appendix A Table of RU Sizes Appendix B HLSCOM Error Messages Appendix C HLSRDT Error Messages Appendix D D-Series Operating System Considerations Overview of D-Series SNAX/HLS D-1 D-Series and C-Series Networking Restrictions High-PIN Support by SNAX/HLS Configuration Parameters D-2 D-2 D-2 Process, File, Device, and Volume Names File Name Syntax D-3 Process Name Syntax D-3 D-3 Glossary Glossary–1 Index Figures Index–1 Figure 1-1. SNAX/HLS in a Tandem Expand Network Figure 1-2.
Contents Table 4-1. HLSRDT Command Summary Table 4-2. DEFINITE-RESPONSE-IND Returned to Application Table 4-3. FM Header Format Table 5-1. SNAX/HLS Configuration Parameters Table 6-1. HLSCOM Command Summary 6-5 Table 7-1. Selection of Response Protocols 7-1 Table A-1. RU Sizes Table B-1.
Contents (This page left intentionally blank) xii 104705 Tandem Computers Incorporated
About This Manual The principal purpose of SNAX High-Level Support (SNAX/HLS) is to allow Tandem application programs to communicate with IBM Systems Network Architecture (SNA) devices and SNA host programs. Little SNA knowledge is required of the application programmer. This manual is designed for individuals responsible for planning, installing, and configuring SNAX/HLS. Section 1 of this manual provides an overview of SNAX/HLS. Section 2 is a guide to planning the SNAX/HLS environment.
About This Manual Tandem Manuals Tandem Manuals The following manuals also pertain to SNAX/HLS: SNAX/HLS Application Programming Manual SNAX/HLS Diagnosis and Support Manual The following Tandem manuals describe SNAX/XF and SNAX/CDF configuration: SNAX /XF Configuration and Control Manual SNAX /XF Management Programming Manual SNAX/CDF Configuration and Control Manual SNAX /CDF Management Programming Manual Related IBM The following list identifies some of the more important IBM SNA manuals: Documents Sy
Notation Conventions The following list summarizes the conventions for syntax presentation in this manual. Notation Meaning UPPERCASE LETTERS Uppercase letters represent keywords and reserved words; enter these items exactly as shown. Lowercase italic letters represent variable items that you supply. Brackets enclose optional syntax items. A group of vertically aligned items enclosed in brackets represents a list of selections from which you can choose one, several, or none.
Notation Conventions (This page left intentionally blank) xvi 104705 Tandem Computers Incorporated
1 Product Overview Introduction SNAX/High-Level Support (SNAX/HLS) consists of several programs and support files that jointly form a subsystem whose purpose is to allow easy communication between Tandem application programs and a wide range of SNA devices and software products (including software running in IBM hosts in different domains).
Product Overview Introduction Figure 1-1.
Product Overview Introduction SNAX/HLS and the Tandem SNA Access Method SNALU Interface The SNAX/HLS process gains access to the SNA network by opening a SNALU LU under the control of the Tandem SNA access method, for example SNAX/XF or SNAX/CDF. In the case of SNAX/XF, this is a SNAX/XF LU, whose name is of the form: $line–name.#lu–name In the case of SNAX/CDF, the resource being opened is actually an APPL that has been defined to a SNAX/CDF process.
Product Overview Introduction SNA Features Supported by SNAX/HLS SNAX/HLS follows the SNA architectural specifications given in the IBM SNA Format and Protocol Reference Manual.
Product Overview The Application Interface Principal Parts of SNAX/HLS SNAX/HLS is a comprehensive system of programs that implements the operational environment. The principal components are: The SNAX/HLS main module (HLSOBJ), which performs SNA services for requesting applications. The Resource Definition language and compiler (HLSRDT), which are used to define the characteristics of sessions and the application interface that is used.
Product Overview The Application Interface Verb Names SNAX/HLS makes every attempt to use verb and modifier names that are easy to understand. Application programmers can thus avoid SNA jargon such as brackets (uninterruptible units of work), chains (logical messages), and request shutdown sequences (orderly termination of communication). Table 1-1 shows SNA and SNAX/HLS terms that are similar in meaning. Each SNA term is followed by the equivalent SNAX/HLS term and a brief definition. Table 1-1.
Product Overview The SNAX/HLS Server Process The SNAX/HLS Server The SNAX/HLS server process is a multithreaded process that interfaces both to the Process SNAX/HLS application and to the SNALU interface of the Tandem access method, that is, SNAX/XF or SNAX/CDF. Its primary functions are to perform verb requests and to produce verb replies for applications. Typically, verb requests result in one or more SNA messages flowing to the session partner on behalf of the application, as shown in Figure 1-2.
Product Overview The SNAX/HLS Server Process Figure 1-2.
Product Overview The SNAX/HLS Server Process Session Control Verbs An application program uses SNAX/HLS verbs to establish communication with a session partner, to manage the transmission and reception of data, and to discontinue communication. Table 1-2 shows verbs used to establish and discontinue sessions as well as miscellaneous verbs. Table 1-2. Verbs and Sessions Verbs to Establish Sessions Verb Function HLS-ALLOCATE HLS-OPEN OPEN-SESSION Define the session partner.
Product Overview Resource Definition Data-Transfer Verbs Table 1-3 shows verbs used to transfer data between an application program and its session partner: Table 1-3. Data-Transfer Verbs Verb Function SEND-DATA RECEIVE-DATA SEND-AND-RECEIVE-DATA Send data to the session partner. Retrieves information from the receive queue. Sends data to session partner and then queues a RECEIVE-DATA verb. Sends a response to partner’s request. Requests permission to send data.
Product Overview Trace Analysis Creating A RDT File The following example shows a typical session creating and using a RDT file. 1. Edit the Source file: > EDIT RDTTEXT {Perform changes} *EXIT 2. Compile the RDTTEXT file: > RUN HLSRDT / IN RDTTEXT, OUT $S.#LP / RDTDATA 3. Run HLSOBJ, passing the newly generated RDTDATA table: > RUN HLSOBJ/IN RDTDATA,OUT out—file,& NAME hls—process—name,NOWAIT/ Log * The Operator Interface A command interface, HLSCOM, is delivered with SNAX/HLS.
Product Overview Trace Analysis Trace Analysis The SNAX/HLS Trace Analysis Program (HLSTAP) allows you to format and display trace information in a meaningful, high-level format. Using HLSCOM, you can configure four levels of tracing: Verb input/output. This trace of all verb requests and replies helps you troubleshoot application programs. LU service calls. This traces all the calls SNAX/HLS makes to its LU Services layer.
2 Planning the SNAX/HLS Environment SNAX/HLS requires you to know little about SNA protocol requirements of the session partner so you can concentrate on the business application. This characteristic of SNAX/HLS requires careful planning of both the Tandem and partner SNA environments by people knowledgeable in these areas. This section presents an overview of the steps in planning the environment. Following the overview are suggestions for planning each step.
Planning the SNAX/HLS Environment Step 1. Partner Requirements Planning The SNAX/HLS product always adheres to the formal protocol but allows some departures from protocol on the receiving side of a transmission. This permits the use of certain SNA devices that do not adhere strictly to SNA protocol. See Section 7, “Interpreting SNA Protocol” for more information on the use of SNA protocols. Tandem system analysts, VTAM/NCP system analysts, and IBM subsystem programmers should be responsible for this step.
Planning the SNAX/HLS Environment Step 1. Partner Requirements Planning Use of Function Management Headers (FMHs) Some programmable controllers require the use of FMHs. (See the SNA references listed in the Preface.) The program in the controller determines this requirement. The use of FMHs is fully supported by SNAX/HLS. The SNAX/HLS application is responsible for placing the FMH in the buffer of a message to be sent and for analyzing any FMH returned in the reply buffer.
Planning the SNAX/HLS Environment Step 2. Planning SNAX Requirements Special Device Data Streams Implementing an emulation of a 327x display device is a major effort. It is therefore recommended that communication with such a session partner employ data records without screen control fields. The partner can process such data using unformatted operations (that is, no BMS map under CICS or null MFS under IMS).
Planning the SNAX/HLS Environment Step 2. Planning SNAX Requirements Planning Communication Links To plan communication links, it is important to understand the capabilities of both modems and devices, because SNAX/XF line definitions must be consistent with device or host features and with the telephonic capabilities of the communications channel. If the device or host is close to the Tandem system, you should examine the possibilities of using relatively inexpensive modem eliminators.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs Planning Codeset Translation The natural codeset for the Tandem system is ASCII. If the device can use the ASCII codeset, it might save computation resources to do so. If, however, the device (or host) must use EBCDIC code, either the application must work in the EBCDIC codeset, or conversion must be performed. Code conversion can be accomplished either by SNAX/XF, or by SNAX/HLS.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs For those applications where SNAX/HLS is used to control the primary half of the session, the BIND message used to set up the session is derived from one of two sources: For Primary-Acquire sessions, the primary partner unilaterally issues a BIND. The BIND information is based upon the name in the profile, which identifies one of the BIND messages you've defined. For Primary-Accept sessions the primary partner receives a CINIT.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs SNAX/CDF completes, not when the session partner acknowledges the message. In this case, completion of the verb cannot be construed as the session partner’s acceptance of the message. SNAX/HLS applications must contain logic to handle situations where the completion of a SEND verb is followed later by a RC-REQUEST-REJECT return code on the receive queue regarding a previous message.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs Definite-response chains—require each message to request explicit acknowledgement. This means message delivery and acceptance can be known to the message sender. Normally, a SNAX/HLS application uses immediate-request mode and definite-response chains if verb completion is to be construed as acceptance by the session partner.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs Common FM Usage BIND bytes 6 and 7 determine attributes that apply to the session as a whole. Session Segmenting Support. This attribute determines whether segmentation can occur for the session. Segmentation refers to the division of chain elements into smaller packets for transmission. This attribute is not interpreted by SNAX/HLS. In the BIND message, this attribute is indicated in byte 6, bit 0.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs Alternate Code Set Allowed This field determines whether the alternate code selection bit in the RH is examined. Set this field to 0. SNAX/HLS verbs do not allow the setting of the code select bit in the RH. This attribute is not interpreted by SNAX/HLS. In the BIND message, this attribute is indicated in byte 6, bit 4.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs Normal Flow Send/Receive Mode This attribute determines how the data flow control (DFC) protocol machines behave in processing user messages. Informally, DFC protocol machines are set to process inbound and outbound messages either simultaneously (full duplex) or serially (half duplex). SNAX/HLS supports the following attributes: FDUX (full duplex). Messages flow in each direction independently.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs In the BIND message, this attribute is indicated in byte 7, bit 3. In HLSRDT, this attribute is specified by the BIND attribute CONTENTION-WINNER, where: SECONDARY corresponds to 0 in the BIND message and PRIMARY corresponds to 1 in the BIND message. Alternate Code Processing Indicator This field is not interpreted by SNAX/HLS. In the BIND message, this attribute is indicated in byte 7, bits 4 and 5.
Planning the SNAX/HLS Environment Step 3. Planning Session BINDs Maximum RUs These fields select the maximum-length message segment to be transmitted between session partners. SNAX/HLS permits a maximum length of 30720 bytes, but some devices and some IBM products require smaller chunks of the message to be transmitted. Set these fields to match the device controller or the IBM product configuration. Appendix A shows how maximum RU sizes are encoded in BIND messages.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment PS Usage The PS usage field is not interpreted by SNAX/HLS. In the BIND message, the PS usage field is indicated in bytes 15-25. In HLSRDT, this attribute is specified by the BIND attribute, PS-USAGE. Primary LU Network Name This field is critical when the SNAX/HLS application is the primary session partner.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment Because the LU name is communicated as a standard Tandem file name that encodes the identity of both the SNAX/HLS server and the LU name, it can be used in the OPEN (to establish communication with the SNAX/HLS server), allowing the program to omit the LU name from the HLS-ALLOCATE or OPEN-SESSION verb. This feature is not available in a Screen COBOL (SCOBOLX) environment that uses the server interface.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment The designer must make a critical choice as to the creator of the SNAX/HLS processes. SNAX/HLS can be created outside the Pathway system or under the control of PATHMON. If SNAX/HLS is created outside of Pathway, the operator has dynamic control of the CPU assignments of SNAX/HLS, the logging files, and so on. If created inside Pathway, these decisions must be predefined in the configuration.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment MAXTERMDATA. The only SCOBOLX requester delivered with SNAX/HLS is the APS system. The information required to set this value can always be obtained from a SCUP INFO DETAIL command on the HLSP program libraries. A value of 23,000 is suggested for APS. PROGRAM. The standard Pathway configurations delivered with SNAX/HLS always specify PATHTCP2.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment SET TERMINAL Parameters The SET TERMINAL parameters should be specified as follows. FILE. (For SNAX/XF) Provided that your application extracts server class and LU names as outlined above, you use this parameter to convey the identity of the session partner by providing an entry of the form: $HLS-process-name.#SNAX/XF-line-name.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment MAXLINKS. This parameter is a global server parameter that directly affects SNAX/HLS performance. MAXLINKS is the number of file opens of SNAX/HLS that the TCP is allowed. Be sure that the MAX^POCB of the SNAX/HLS server is great enough to handle MAXLINKS plus HLSCOM requirements. The calculation below gives the exact link demand of a SNAX/HLS process. You can let MAXLINKS default to unlimited.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment If this attribute is selected, SNAX/HLS will use read buffers whose size is sufficient to accommodate the largest possible SSCP-LU message. This value is in the range 256 to 30,720 as determined by a configuration parameter, SSCPTEXTSIZE, and may be modified by the operator. Its default value is 4,096. Large reads consume valuable resources.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment Receipt of these messages can be enabled two ways: The attribute can be set in the PROFILE, or your application can issue the SM message using the HLS-FLOW-CONTROL verb. If your half-session is not enabled for flow control messages, the SNAX/HLS server rejects any of the above messages from your partner with sense code %H1003.
Planning the SNAX/HLS Environment Step 4. Planning the Application Environment Accept Bind When your application is acting as the primary LU, you can elect to establish sessions either by acquisition (your side issues the BIND unilaterally) or by acceptance (your side waits for a CINIT message and then issues the BIND). In the latter case, the Tandem SNA access method SNAX/CDF supplies a suggested BIND image in the text of the CINIT message.
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards An application program using SNAX/HLS, of course, does not directly see the failure of either SNAX/XF or SNAX/CDF, or SNAX/HLS. Instead, SNAX/XF or SNAX/CDF produces SNA sense-code errors for all subsequent data operations, and SNAX/HLS produces a RETURN-CODE, RC-POSSIBLE-DATA-LOSS on all session-oriented verbs until the session is deallocated.
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards !----------------------------------------------! ! The Procedure "ANALYZE^READ^RESPONSE" is ! ! called when a piece of data is received. ! !----------------------------------------------! PROCEDURE ANALYZE^READ^RESPONSE; BEGIN !--------------------------------------------! Test the completion code to eliminate errors. !--------------------------------------------IF RECEIVE^DATA^REPLY.RETURN^CODE <> 0 THEN BEGIN . .
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards IF kind < 0 THEN BEGIN . . ! We have an FMH in the data. . ! The first byte of the data is the FMH length, . ! followed by the FMH type byte, followed by FMH data. . . ! FMHs may be concatenated, but we assume that . ! only one FMH is present. . . FMH^CONTINUED := RECEIVE^DATA^REPLY.USER^DATA.<8>; . . FMH^LENGTH := RECEIVE^DATA^REPLY.USER^DATA.<9:15>; . . FMH^TYPE := RECEIVE^DATA^REPLY.USER^DATA[1].<8:15>; . .
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards DT^INTERRUPT^REQUEST -> . . ! We have an interrupt message. The use of interrupt . ! messages is application-specific. . ! The important observation is not to process . ! this message as a message from session partner. . . CALL PROCESS^INTERRUPT^MESSAGE; . DT^SSCP^DATA -> . . ! We have a message from the SSCP. The PROFILE must . ! allow delivery of SSCP messages for us to get here. .
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards DT^SIGNAL -> . . ! We have received an SIG message. Most frequently . ! this results from an ATTENTION key on a terminal . ! to signal that the partner wants to send data. . ! This use of the SIG message is restricted to . ! half-duplex protocols. . ! The SIG message has 4 bytes (two integers) . ! of data. The ATTENTION event is signalled by the . ! value %H0001 in the first two bytes. . ! . ! Other codes are detected here, .
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards . . CALL PROCESS^BIND^CINIT^DATA; DT^SESSION^CLOSED -> . . ! This message signals that your partner has closed the . ! session. This can occur if you separately allocate . ! and open your session (that is, you used HLS-ALLOCATE . ! and HLS-OPEN). . . CALL PROCESS^PARTNER^CLOSURE; DT^FLOW^CONTROL -> . . ! This message signals receipt of a flow control message. . ! This can occur only if you have enabled receipt of such .
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards It is recommended that the installation construct a standard subroutine, procedure, or server to process non-RC-OK verb replies. The routine would accept the verb reply, call CONVERT-ERROR-CODE, perform appropriate logging, and furnish the RETRY-ACTION-CODE back to the calling procedure.
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards RA-NON-RETRYABLE. If the value is RA-NON-RETRYABLE, then the request violates the SNA protocol specified by the current bind. The request is not executable until the session is CLOSED and restarted under a BIND that allows the request. In general, a request that causes such a value to be returned causes session termination by either the SNAX/HLS server or the session partner.
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards These indicators provide the HLS application with information about which state to assume so that mismatches and RA-DEFER responses can be avoided. If ENTER-SEND-STATE-IND is set on a RECEIVE-DATA reply, it signals that the application should now send data. In effect, the indicator, when it contains “Y,” should be interpreted as “The session partner has relinquished the right to send data, and is waiting for me to send something.
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards Pathway CONFIGURATION: RESET TERM SET TERM FILE $HLS1.#SNA1.TERM1 SET TERM INITIAL ALLOCATE-PROG SET TERM TCP TCP1 ADD TERM1 .................................... RESET TERM SET TERM FILE $HLS1.#SNA1.TERM11 SET TERM TCP TCP2 SET TERM INITIAL ALLOCATE-PROG ADD TERM11 RESET TERM SET TERM FILE $HLS2.#SNA2.TERM1 SET TERM INITIAL ALLOCATE-PROG SET TERM TCP TCP2 ADD TERM12 ...................................
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards 01 TERM-FILE-REG-X REDEFINES TERM-FILE-REG. 05 DOLLAR-SIGN pic X. 88 SEVEN-CHARACTER-FORM VALUE "$". 05 SERVER-NAME-7 pic X(07). 05 FILLER pic X(16). . 01 LINKAGE-INFO. 05 DEV-SERVER pic X(07). 05 SESS-ID pic 9(04) comp. PROCEDURE DIVISION. A-MAIN. MOVE TERMINAL-FILENAME TO TERM-FILE-REG. IF SEVEN-CHARACTER-FORM MOVE SERVER-NAME-7 TO DEV-SERVER ELSE MOVE SERVER-NAME-6 TO DEV-SERVER. MOVE TERMINAL-FILENAME TO LU-NAME. . .
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards As long as individual fields are not accessed as destination fields, no problems arise. As soon as a program accesses them as destination fields, either on a MOVE or on some arithmetic operation, SCOBOLX insists that the resultant value be in the range 0 through 9,999 or -9,999 through 9,999, depending upon how the field was defined.
Planning the SNAX/HLS Environment Step 5. Planning for Programming Standards 01 APPLICATION-TAGS. 02 SEND-NUMBER 02 RCV-NUMBER pic XX. pic XX. 01 APPLICATION-VALS. 02 SEND-VAL 02 RCV-VAL pic S9(5) comp. pic S9(5) comp. 01 APPLICATION-VALX REDEFINES APPLICATION-VALS. 02 FILLER pic XX. 02 SEND-VALX pic XX. 02 FILLER pic XX. 02 RCV-VALX pic XX. (Assume values are in APPLICATION-VALS) MOVE send-valx TO send-number. MOVE rcv-valx TO rcv-number. MOVE application-tags TO recovery-tags OF hls-open-request.
3 Installing SNAX/HLS This section contains the information you need to install SNAX/HLS. Distribution The distribution subvolume for SNAX/HLS contains a set of files that together Subvolume Contents constitute the product. Table 3-1 lists the program files you need to install SNAX/HLS. Table 3-1.
Installing SNAX/HLS Distribution Subvolume Contents Table 3-2 lists other SNAX/HLS Distribution Files. Table 3-2.
Installing SNAX/HLS Distribution Subvolume Contents HLSMSGS Is an edit file that contains controls and text messages used by SNAX/HLS. Your installation can change the controls of these messages. HLSOBJ Contains the SNAX/HLS server main module. This is a multithreaded process that handles the processing of SNAX/HLS verbs and interfacing to the Tandem SNA access method (SNAX/XF or SNAX/CDF), using the SNALU interface. HLSPCOD Contains Pathway pseudocode for the APS program requesters using SNAX/HLS.
Installing SNAX/HLS Where to Put Files RDTDATA Is an RDT segment that is the result of compiling the preceding sample RDTTEXT file. This file can serve as a starter RDT for SNAX/HLS initialization. To prepare for application processing, your system programmer should compile RDTTEXT and review the compiler listing to determine the applicability of the sample PROFILES to the needs of your installation. The default location for RDTDATA is $SYSTEM.SYSTEM.
Installing SNAX/HLS Program Security HLSTAP Trace Analysis HUXOBJ Library File The trace analysis program (HLSTAP) can also be placed on $SYSTEM.SYSTEM for ease of use, although this depends on the frequency of trace analysis. It is recommended that HUXOBJ be put on $SYSTEM.SYSTEM since the library location of HLSOBJ, by default, is $SYSTEM.SYSTEM.HUXOBJ. ZHLSTMPL Template File Your installation should use the Install process to install the messages for SNAX/HLS into the system’s template file.
Installing SNAX/HLS Modifying the Message File (HLSMSGS) HLSCOM Security RDT Security Secure HLSCOM as appropriate for normal operations. The sensitive commands (ABEND and ABORT) are under control of the SNAX/HLS process. Production operators, system programmers, and system-capacity planners need access to HLSCOM. If the SNAX/HLS process is executing in an Expand network, set execution security as appropriate to network operation.
Installing SNAX/HLS Modifying the Message File (HLSMSGS) Modifying Retry Action Codes Retry action codes vary from 0 to 3. An installation can change these codes to make application programming easier. For example, when SNAX/HLS returns a nonzero return code, an application program can base its actions on the retry action codes (rather than the return code).
Installing SNAX/HLS Modifying the Message File (HLSMSGS) K-Records (Internal Events). K-records record unusual conditions within SNAX/HLS. Starting in column 7 is a code defining whether the event is to be logged, an EMS event is to be generated (and if so to which collector), or both, according to the following: I No event, no log message. L Log message only. E EMS event only, generated to the primary EMS collector.
Installing SNAX/HLS Using HLSRUN to Configure PATHWAY Using HLSRUN to APS is under the control of Pathway. The TACL macro HLSRUN can be used to set Configure Pathway up standard configurations. The conventions assumed by that procedure are used throughout this manual. To establish the standard environment, you must select a three-character name, such as HLS, from which the procedure automatically derives three process names, two file names, and a server class name.
Installing SNAX/HLS Using HLSRUN to Configure PATHWAY CPU is the CPU number used while starting the HLSOBJ and the Pathway monitor process. DEBUG is used to debug the HLSOBJ file itself and should be used in collaboration with Tandem SSG support staff. LIB file-name designates which library contains your installation’s customized routines. If specified, the file is located using the current #PMSEARCHLIST. LOG file-name designates the file that the HLSOBJ file uses for its logging device.
Installing SNAX/HLS Using HLSRUN to Configure PATHWAY TRACE trace-option designates the setting for the INITIAL^TRACE option used at SNAX/HLS startup. If omitted, the value zero is assumed. (For more information on INITIAL^TRACE, refer to Section 5, “Operating SNAX/HLS.”) TCLPROG pathway-program-file-name designates where the object of the Pathway SCOBOL program file and the corresponding directory is located. The file name portion cannot exceed five characters.
Installing SNAX/HLS Using HLSCMI to Create a SNAX Loop-Back Environment Using HLSCMI to Create a SNAX/XF Loopback Environment SNAX/HLS requires a Tandem SNA access method, (SNAX/XF for example) for SNA communication. Prior to SNAX/HLS initialization, the system programmer should define the environment for the particular Tandem SNA access method being used. For more information on the Tandem SNA access methods SNAX/XF and SNAX/CDF refer to the manuals listed in the Preface.
Installing SNAX/HLS Using HLSCMI to Create a SNAX Loop-Back Environment The procedure automatically assigns LU names of the form: PpuLlu where pu is the PU number (0, 1, 2, ...) and lu is the LU number (0, 1, 2, ...). The procedure lists the names of the LUs it defines. For example, the following statement creates eight LUs on three PUs on primary line $SNA1 to secondary line $SNA2: HLSCMI PRI $SNA1, SEC $SNA2, LU 8 SNAX-HLS/HLSCMI - (T9089C10 15Mar88 b20) Creating LoopBack configuration...
Installing SNAX/HLS Using HLSCMI to Create a SNAX Loop-Back Environment (This page left intentionally blank) 3–14 104705 Tandem Computers Incorporated
4 Using the HLSRDT Utility Introduction The SNAX/HLS operating environment presumes the existence of a database known as the resource definition table (RDT). This table contains PROFILE, BIND, and INIT data. The application program, at execution time, references an entry in this database through the use of the PROFILE name. The PROFILE entries define many characteristics of the session about to begin.
Using the HLSRDT Utility Running HLSRDT obj-file specifies the name of the RDT database that will be built. If a file of the same name already exists and its file code is the same as that of RDT database, that file is deleted. If the file exists but its file code is different from that of RDT database, the program terminates with a diagnostic message. command optionally specifies one of the commands recognized by HLSRDT.
Using the HLSRDT Utility Syntactic Elements mapname Represents the mapping table to be used for sessions established under this PROFILE. The name is case-insensitive, up to 50 characters long, must start with an alphabetic character, and contain only alphanumerics. Preparing Commands You specify commands on text lines. Each text line is interpreted as explained in the following paragraphs.
Using the HLSRDT Utility Command Dictionary Command Dictionary This subsection presents a dictionary of HLSRDT commands. Table 4-1 summarizes the commands. A detailed description of each command follows the table. The commands are listed in alphabetical order. The description of each command includes an introductory paragraph, an explanation of the command syntax, a list of considerations, and one or more examples. Table 4-1.
Using the HLSRDT Utility Command Dictionary ADD Command The ADD command adds a new named object of the type specified to the saved set of objects being saved for eventual inclusion in the RDT database. The values of the object are those contained in the working image, as adjusted by the preceding set of SET commands. ADD { PROFILE } name-8 { BIND } { INIT } name-8 is the name by which the object will be known in the application program.
Using the HLSRDT Utility Command Dictionary CMDSYS Command The CMDSYS command sets the default system for expansion of all file names (except OBEY file names). CMDSYS [ system-name ] system-name is a system name. The initial setting is the default system used by the command interpreter when HLSRDT is started.
Using the HLSRDT Utility Command Dictionary CMDVOL Command The CMDVOL command sets the default volume and subvolume names for the expansion of all file names (except OBEY file names). CMDVOL [ $volume-name [ .subvolume-name ] ] [ subvolume-name ] volume-name is a volume name. The initial setting is the default volume used by the command interpreter when HLSRDT was started. If volume-name is omitted, the previous setting is used. subvolume-name is a subvolume name.
Using the HLSRDT Utility Command Dictionary DELETE Command The DELETE command deletes an object that was previously saved with an ADD command. DELETE { PROFILE } name-8 { BIND } { INIT } name-8 is the name of the object in the saved set. This command does not affect the contents of the working images.
Using the HLSRDT Utility Command Dictionary ENV Command The ENV command displays the current defaults for file-name expansion. ENV Example The following command displays the CMDVOL and OBEYVOL file names. @ENV Cmd defaults: Obey defaults: Assumed line: @ 104705 Tandem Computers Incorporated $CRUDE.HLSRDT $CRUDE.
Using the HLSRDT Utility Command Dictionary EXIT Command The EXIT command is processed in one of two ways: If HLSRDT is running interactively, the EXIT command saves the current RDT database (as described in the SAVE command) and stops the current HLSRDT. If HLSRDT is running noninteractively, the EXIT command exits the current OBEY file and reduces the nesting level of OBEY-file execution. If the EXIT command reduces the level to zero, the HLSRDT process is terminated.
Using the HLSRDT Utility Command Dictionary FC Command The FC command fixes the last interactive command entered.
Using the HLSRDT Utility Command Dictionary FILES Command The FILES command lists the files on a subvolume. FILES [ $volume-name [.subvolume-name] ] volume-name is a Guardian volume name. subvolume-name is a Guardian subvolume name. Consideration The current default values supplied by CMDSYS and CMDVOL are used for expansion of the volume-name and subvolume-name. Examples If the ENV command displays the following output: @ENV Cmd defaults: Obey defaults: Assumed line: @ $DALLAS.$BIGD.TEXAS $CRUDE.
Using the HLSRDT Utility Command Dictionary The following command displays the names of the files in the subvolume \DALLAS.$CRUDE.TEXAS: @FILES $CRUDE \DALLAS.$CRUDE.
Using the HLSRDT Utility Command Dictionary HELP Command The HELP command displays the syntax of HLSRDT commands. HELP [ topic ] topic specifies one of the following topics: command-name is the name of an HLSRDT command for which the syntax is to be displayed. parameter is any parameter value that is enclosed in angle brackets (< >) when displayed by the command or ALL option. The angle brackets must be included. ALL is a keyword that requests that the syntax for all HLSRDT commands be displayed.
Using the HLSRDT Utility Command Dictionary The following command displays the syntax for the LU-specifier parameter (you must type the angle brackets). @HELP Specifies one or more sessions in one of the forms: $LINE.#LU the indicated session $LINE.* all sessions on that line *.
Using the HLSRDT Utility Command Dictionary INFO Command The INFO command lists the names of all objects currently in the saved set. INFO [ PROFILE ] [ BIND ] [ INIT ] The INFO command by itself lists all objects of all types in the saved set; the INFO command with an object-type keyword displays all objects of the named type. Examples The following INFO command produces a combined list of all PROFILE, BIND and INIT records currently known.
Using the HLSRDT Utility Command Dictionary LOG Command The LOG command directs a copy of the input commands and output generated by HLSRDT to a file. LOG directive directive is one of the following: TO file-name specifies the name of the file to receive the copy of the commands and output. This form of the command initiates the logging function. STOP closes the log file and stops all logging.
Using the HLSRDT Utility Command Dictionary OBEY Command The OBEY command causes commands to be read from a specified file. Such an OBEY file can itself contain OBEY command(s). The nesting of OBEY files can be up to three levels. Commands are read from the named file and processed until an end-of-file character, an EXIT command, the BREAK key, or an error is encountered.
Using the HLSRDT Utility Command Dictionary OBEYSYS Command The OBEYSYS command sets the default system for file-name expansion of files in OBEY commands. OBEYSYS [ system-name ] system-name is a system name. The initial setting is the system used by the command interpreter when HLSRDT is started. If system-name is omitted, OBEYSYS is cleared (there is no default), thus permitting reference to seven-character local device names that are too long to reference in network form.
Using the HLSRDT Utility Command Dictionary OBEYVOL Command The OBEYVOL command sets the default volume and subvolume for expansion of OBEY file names. OBEYVOL [ $volume-name [ .subvolume-name ] ] [ subvolume-name ] volume-name is a volume name. The initial setting is the default volume used by the command interpreter when HLSRDT was started. If volume is omitted, the previous setting is used. subvolume-name is a subvolume name.
Using the HLSRDT Utility Command Dictionary RESET Command The RESET command sets all attributes (or a particular attribute) of the working image to default values. RESET { PROFILE } [ attribute ] { BIND } { INIT } Example The following command resets the working BIND image to standard defaults. @RESET BIND @ The following command resets the TRANSLATE attribute of the working PROFILE image to its standard default.
Using the HLSRDT Utility Command Dictionary SAVE Command The SAVE command creates the RDT database without exiting the program. A similar save is performed automatically when you use the EXIT command (or CTRL-Y). SAVE The information is saved to the file specified in the RUN HLSRDT command. All the PROFILEs, INITs, and BINDs in the current RDT database are saved. Note that if you added INITs or BINDs that were not referenced from any PROFILE, they will not be saved in the database.
Using the HLSRDT Utility Command Dictionary SET Command The SET command assigns a value to a given attribute of a named object. SET { PROFILE } attribute value { BIND } { INIT } attribute is one of the attributes associated with the object, or the special attribute LIKE. value is a value appropriate to the named attribute. The LIKE attribute differs in that it sets all the attributes of the working copy to equivalent values from the referenced PROFILE, BIND, or INIT record.
Using the HLSRDT Utility Command Dictionary SHOW Command The SHOW command displays the current values maintained in the working image for an object or a specific attribute of an object. SHOW { PROFILE } [ attribute ] { INIT } { BIND } In the case of showing BIND attributes, some attribute value may be overridden or outlawed by specific FM and TS values. These are SNA rules.
Using the HLSRDT Utility Command Dictionary @SHOW BIND BIND: bind_type: fm_profile: pri_chain_use: pri_rq_mode: pri_chain_protocol: pri_two_phase_commit: pri_compression_ind: pri_eb_send: pri_send_pacing_size: pri_send_staging pri_recv_pacing_size: pri_max_ru: no_segments: brkt_reset: alt_code_use: bis_sent: send_recv: contention_winner: hdx_ff_reset_sender: ps_usage: plu_name: @ NONNEGOTIABLE lu_session_type: 3 ts_profile: MULTIPLE_RU sec_chain_use: IMMEDIATE sec_rq_mode: EXCEPTION sec_chain_protocol: NO
Using the HLSRDT Utility Command Dictionary SYSTEM Command The SYSTEM command is used to set the default system for all file-name expansions. The SYSTEM command is equivalent to entering a CMDSYS command and an OBEYSYS command, both with the same system-name specification. SYSTEM [ system-name ] system-name is a system name. The initial setting is the default system name used by the command interpreter when HLSRDT was started. If system-name is omitted, the default system name is cleared.
Using the HLSRDT Utility Command Dictionary VERSION Command The VERSION command causes HLSRDT to display its version banner. VERSION Consideration The banner line consists of: 1. The product name—SNAX-HLS/HLSRDT 2. The product number—T9089onn—where o is the release level (for example, A, B, C) and nn is the interim level (for example, 00, 10, 25) 3. The object release ID date in ddmmmyy format 4.
Using the HLSRDT Utility Objects and Attributes VOLUME Command The VOLUME command sets the default volume and subvolume for expansion of all file names. The VOLUME command is equivalent to entering a CMDVOL command and an OBEYVOL command, both with the same volume and subvolume specifications. VOLUME [ $volume-name [ .subvolume-name ] ] [ subvolume-name ] volume-name is a volume name. The initial setting is the default volume used by the command interpreter when HLSRDT was started.
Using the HLSRDT Utility Objects and Attributes Objects and Attributes The HLSRDT command language controls three types of objects: PROFILE, BIND, and INIT. There is one working area for each object type that is implied in the ADD, SHOW, and RESET commands. Each object type has its own set of attributes.
Using the HLSRDT Utility Objects and Attributes BID-REJECTION specifies how SNAX/HLS handles the rejection of bids on the part of the first speaker. The three options are: NO-RTR This negative response to a BID (or a begin-bracket RU), is generated automatically by SNAX/HLS. The bidder has no choice but to retry the BID at some future time. The first speaker will not necessarily prompt the bidder. The local application is unaware of the occurrence of this event.
Using the HLSRDT Utility Objects and Attributes CHARMAP This PROFILE attribute is a map name that specifies the mapping table to be used for sessions established under this profile. The name is case insensitive and can be up to 50 characters long. It must start with an alpha character and contain only alphanumerics. If omitted, the default map is implied. The default map is specified by the CHARMAPNAME configuration parameter, which itself defaults to the standard Tandem ASCII-to-EBCDIC translation.
Using the HLSRDT Utility Objects and Attributes FORCE-RTS This PROFILE attribute has the value type yesno. The default is NO. FORCE-RTS affects the behavior of the REQUEST-SEND-STATE verb, detailed in the SNAX/HLS Application Programming Manual. If the attribute has the value YES, an SNA SIG request with signal code %H0001 is sent whenever the REQUEST-SEND-STATE verb request is issued, regardless of the state of the normal SNA session flows.
Using the HLSRDT Utility Objects and Attributes MAX-REQUESTS This PROFILE attribute has the value type integer. The default value is 2. MAX-REQUESTS specifies the maximum number of verbs that can be queued by the application at any one time. The recommended value of 2 is based upon a permanently queued read-type verb and a second send-type verb. Larger values are unusual. The value must be positive.
Using the HLSRDT Utility Objects and Attributes RESPONSE-TYPE This PROFILE attribute has the possible values 1, 2, or 3. The default value is 1. RESPONSE-TYPE specifies the initial response type that is requested. The valid values are 1, 2 or 3, corresponding to DR1, DR2, or DR1&DR2 respectively. This value can be modified by the application program. The choice of DR values used on any given message can imply certain side effects, especially if the partner is IMS or a similar product.
Using the HLSRDT Utility Objects and Attributes TRANSLATE This PROFILE attribute has the value type yesno. The default value is NO. TRANSLATE specifies whether data is to be converted between an outbound/external format and an inbound/internal format. If selected, the interchange code set (the data sent to and received from SNAX) is in the outbound format, and the presentation code set (the data sent to and received from the application in HLS verbs) is in the inbound format.
Using the HLSRDT Utility Objects and Attributes WANT-BIND-DATA This PROFILE attribute has the possible keywords NONE, USER-DATA, or ALL. The default value is NONE. WANT-BIND-DATA specifies whether the information from BIND or CINIT records should be delivered to the application, and if so, in what form. If the NONE value is selected, the application program does not receive any notification of BIND or CINIT data.
Using the HLSRDT Utility Objects and Attributes BIND Attributes The attributes that can be specified for BIND objects are: ALT-CODE-ID ALT-CODE-USE BIND-QUEUING BIND-TYPE BIS-SENT BRKT-RESET BRKT-TERM CONTENTION-WINNER FM-HEADER-USE FM-PROFILE HDX-FF-RESET-SENDER LU-SESSION-TYPE NO-SEGMENTS PLU-NAME PS-USAGE RECOVERY-MODE SEND-RECV SEQNO-USE TS-PROFILE USER-DATA The following BIND attributes apply, independently, to both primary and secondary partners: PRI-CHAIN-PROTOCOL PRI-CHAIN-USE PRI-COMPRESSION-IN
Using the HLSRDT Utility Objects and Attributes BIND-TYPE This BIND attribute has the possible keywords NEGOTIABLE or NONNEGOTIABLE. The default is NONNEGOTIABLE. TYPE identifies the type of BIND image that is sent. Negotiable binds are used when the secondary LU is expected to modify the BIND information and return, in the BIND response, the updated values. If the resultant values are unacceptable to the primary, the session should be unbound.
Using the HLSRDT Utility Objects and Attributes FM-HEADER-USE This BIND attribute has the value type yesno. The default value is NO. FM-HEADER-USE specifies whether formatted headers will be used in this session. FM-PROFILE This BIND attribute has the possible values 2, 3, 4, 7, or 18. The default value is 4. FM-PROFILE specifies the function management profile number. HDX-FF-RESET-SENDER This BIND attribute has the possible keywords PRIMARY or SECONDARY. The default value is SECONDARY.
Using the HLSRDT Utility Objects and Attributes PS-USAGE This BIND attribute has the value type 22-hex-digits. The default value is all zeros. PS-USAGE specifies the presentation services usage field. The field consists of 11 bytes of data and is entered by specifying 22 bytes of hexadecimal data. Since the interpretation of this data is application dependent, SNAX/HLS cannot interpret this information. RECOVERY-MODE This BIND attribute has the possible keywords LOSER or SYMMETRIC. The default is LOSER.
Using the HLSRDT Utility Objects and Attributes PRI-CHAIN-PROTOCOL This BIND attribute has the possible keywords NONE, EXCEPTION, DEFINITE, or ANY. The default is EXCEPTION. PRI-CHAIN-PROTOCOL specifies what type of response chains will be issued by the primary half session. The NONE option allows datagram service: messages are sent without acknowledgement of success or failure. This provides minimum message overhead, but depends upon higher-level, application-oriented validation techniques.
Using the HLSRDT Utility Objects and Attributes PRI-EB-SEND This BIND attribute has the value type yesno. The default value is NO. PRI-EB-SEND specifies whether the primary half session is allowed to send end brackets. If neither the primary nor the secondary have this option enabled, indicating that neither can send end brackets, then no brackets are used in the protocol. In most situations, only the primary half session can send end brackets. PRI-MAX-RU This BIND attribute has the value type rusize.
Using the HLSRDT Utility Objects and Attributes PRI-SEND-PACING-SIZE specifies the size of the primary send pacing window. It is used only by the primary partner and only when two-stage pacing is selected for this flow. Otherwise, SEC-RECV-PACING-SIZE is used. PRI-SEND-STAGING This BIND attribute has the value type yesno. It specifies single or two stage pacing for the primary-to-secondary normal SNA flow. The default value of NO specifies single stage pacing.
Using the HLSRDT Utility Objects and Attributes SEC-MAX-RU This BIND attribute has the value type rusize. The default value is 1,024. SEC-MAX-RU specifies the largest RU that the secondary half session will send. See the discussion for PRI-MAX-RU. SEC-RECV-PACING-SIZE This BIND attribute has the value type integer, and its value is in the range 0 through 63. The default value is 0. This BIND attribute specifies the size of the secondary receive pacing window.
Using the HLSRDT Utility Objects and Attributes INIT Attributes Following are the attributes that can be specified for INIT objects. APPL-NAME MODE-NAME PASSWORD REQUESTER-ID USER-DATA APPL-NAME This INIT attribute has the value type name-32. The default value is blanks. APPL-NAME specifies the name that is carried in the INIT-SELF, starting at byte 12.
Using the HLSRDT Utility Using HLSRDT: Examples USER-DATA This INIT attribute has the value type string. The default value is text surrounded by quotes (“ ”). USER-DATA specifies text that is carried in the user-data field of the INIT-SELF. This text can be overridden in the HLS-OPEN request. This field is often used to carry logon or user-identification information to programs like TSO. Using HLSRDT: The following examples show some typical uses of HLSRDT.
Using the HLSRDT Utility Using HLSRDT: Examples Use the ADD PROFILE command to name the PROFILE and add it to the RDT database. In the following example, the PROFILE is named SLUACCPT: @ADD PROFILE SLUACCPT @ SLUACCPT is the same name that application programs use to access this PROFILE.
Using the HLSRDT Utility Using HLSRDT: Examples @SHOW PROFILE PROFILE: hs_polarity: SECONDARY bind_name: response_type: 1 translate: NO want_sscp_text: NO want_flow_control: YES max_requests: 2 single_fmh: NO bid_rejection: NO_RTR Charmap: FRENCH force-rts @SET PROFILE LIKE PLULMO @SHOW PROFILE PROFILE: hs_polarity: PRIMARY bind_name: BDEF response_type: 1 translate: YES want_sscp_text: NO want_flow_control: NO max_requests: 2 single_fmh: NO bid_rejection: NO_RTR Charmap: FRENCH force-rts @ open_mode: ini
5 Operating SNAX/HLS Starting SNAX/HLS Once SNAX/HLS is installed (as described in Section 3, “Installing SNAX/HLS”) and the appropriate Resource Definition Table (RDT) is compiled, you can start the SNAX/HLS process using the RUN HLSOBJ command described in the next subsection. When the SNAX/HLS server is started, the version banner is sent to the log file (if logging is enabled) and an EMS event is generated.
Operating SNAX/HLS Starting SNAX/HLS Format of RUN HLSOBJ Command The RUN HLSOBJ command starts the SNAX/HLS server. In most installations, the only people who use this command are the control operators and system programmers responsible for installing and running SNAX/HLS. This subsection explains the command in detail. RUN HLSOBJ [/
Operating SNAX/HLS Starting SNAX/HLS TERM terminal-name assigns a home terminal to the SNAX/HLS process. Critical messages are written to the home terminal. If a SAVEABEND file is created because of internal errors detected by HLS or because of an ABEND command, the name of the SAVEABEND file is displayed on the home terminal. If this parameter is not given, the default is the home terminal of the command interpreter that started the SNAX/HLS process. Other run options have the standard meanings.
Operating SNAX/HLS Starting SNAX/HLS SNAX/HLS Table 5-1 lists and briefly defines the SNAX/HLS configuration parameters. A Configuration detailed description of each parameter follows the table. Parameters Table 5-1.
Operating SNAX/HLS Starting SNAX/HLS ABEND^ON^ERROR NO is equivalent to DEBUGONERROR YES BACKUPCPU. Specifies the identity of the backup CPU. This parameter can be specified with or without the keyword. If omitted (or specified as -1), the HLS server process runs without a backup. The following examples are equivalent. BACKUPCPU 7,... 7,... The abbreviated form is defined so that the conventional startup sequence can be supported as shown in the following example: RUN /xxx...,CPU 2/ 3... BACKUPDEBUG.
Operating SNAX/HLS Starting SNAX/HLS needed, and is frequently a more economical way to run the subsystem. When operating in this mode, an initial allocation at program startup guarantees enough storage to start the subsystem. Storage is then extended as needed until one of the following happens: The limit set by the Tandem NonStop Kernel on segment size has been reached. The underlying disk file space is unavailable. Virtual memory space is exhausted.
Operating SNAX/HLS Starting SNAX/HLS The parameter value is between 0 and 15. Each bit has the following significance: 8 Trace LU service manager states 4 Trace to and from the SNALU interface 2 Trace data flow control events 1 Trace verb requests and responses LOG or LOGFILE. Either keyword LOG or LOGFILE can be used to identify this configuration parameter.
Operating SNAX/HLS Starting SNAX/HLS MAX^POCB. Is the number of process opener control blocks (POCBs) allocated at SNAX/HLS startup. Each application program that issues a system service OPEN uses one POCB for each file it opens. Configure this parameter to reflect the total number of openers required. This number is augmented to account for SPI openers. The amount by which it is increased may change from release to release or from IPM to IPM. The default value of MAX^POCB is 64. RECEIVEDEPTH .
Operating SNAX/HLS Examples of SNAX/HLS Startup Examples of SNAX/HLS Startup Assumptions About the Examples This subsection shows two examples of how to start the SNAX/HLS server. Both achieve the same result, but differ in the method used to deliver startup parameters. In the first example, startup parameters are included in the RUN HLSOBJ command. In the second example, startup parameters are included in PARAM statements (and omitted from the RUN HLSOBJ command).
Operating SNAX/HLS Examples of SNAX/HLS Startup Example 1: Startup Parameters in RUN Command The following is an example of the startup parameters in the RUN command: 43> 44> 45> 45> 45> 45> 45> 45> 45> 45> 46> Example 2: Startup Parameters in PARAM Statements & & & & & & & The following is an example of the startup parameters in the PARAM statements: 81> 82> 83> 84> 85> 86> 87> 87> 87> 87> 87> 87> 88> 5–10 set inspect SAVEABEND set swap $TEXAS run $SYSTEM.SNAXHLS.HLSOBJ /in $BIGD.DALLAS.
Operating SNAX/HLS Reporting Events Values Used in the Examples In both Example 1 and Example 2, the following values result: ABEND^ON^ERROR (see reverse of DEBUGONERROR) BACKUP^CPU (see BACKUPCPU) DATA^SEG^SIZE (see DATAPAGES) BACKUP^DEBUG (see BACKUPDEBUG) MAX^LUS 40 MAX^POCB 80 INITIAL^TRACE 0 COLLECTOR $0 DATAPAGES dynamic BACKUPCPU 4 BACKUPDEBUG OFF DEBUGONERROR OFF SWAPVOL $TEXAS Log file none RDT file $BIGD.DALLAS.RDTDATA Messages file $SYSTEM.SNAXHLS.
Operating SNAX/HLS Reporting Events The LOG Facility The log file is specified at program initiation using the LOG or LOGFILE startup parameter. Thus, a command that starts the HLSOBJ file of the form: > RUN HLSOBJ/ OUT $s.#log,. . . / LOG *,. . . or > RUN HLSOBJ/. . . / LOG $s.#log,. . . has the effect of specifying the file $S.#LOG as the output log medium.
Operating SNAX/HLS Reporting Events The EMS Facility The primary EMS collector, and up to three alternate EMS collectors, are specified at program initiation. The COLLECTOR option is available for specifying the primary EMS collector, which defaults to $0 on the local node. The options COLLECTOR-1, COLLECTOR-2, and COLLECTOR-3 are available for specifying the alternate collectors.
Operating SNAX/HLS Programmatic Startup Message Volume As noted in the previous discussions, SNAX/HLS uses wait I/O for logging and event generation. This means all tasks under the control of SNAX/HLS are effectively stalled waiting for the completion of the I/O to the LOG or EMS files. If only important events are generated, the delays generated by the LOG and EMS traffic will be small and will have a minimal impact on systems performance.
Operating SNAX/HLS Programmatic Startup The second choice might be difficult because it might involve a modification to existing applications and might be complicated by the fact that the location of the library module must now be made known to the application containing the NEWPROCESS call. Furthermore, the security of both files must allow the fix-up (that is, the user must be allowed write access to the HLSOBJ file).
Operating SNAX/HLS Programmatic Startup (This page left intentionally blank) 5–16 104705 Tandem Computers Incorporated
6 Using the HLSCOM Utility This section provides information about the HLSCOM operating environment, tells you how to run HLSCOM, and includes a detailed command dictionary. Operating HLSCOM provides a command interface through which operators and system Environment programmers can control and monitor the SNAX/HLS server activities.
Using the HLSCOM Utility Running the HLSCOM Program Basic Components The command syntax diagrams in this section contain several syntactic variables (shown in italic font). The definitions of most of these are identical to those used in the Tandem NonStop Kernel. For example, the definition of file-name that applies in Tandem NonStop Kernel applies here also.
Using the HLSCOM Utility Running the HLSCOM Program Running the HLSCOM You can start HLSCOM with the command interpreter RUN command. Program HLSCOM runs in either interactive mode or noninteractive mode. In interactive mode, the HLSCOM IN file and OUT file are the same. By default, this file is the terminal on which the RUN command was issued. HLSCOM also supports IN and OUT process files. In noninteractive mode, the HLSCOM IN file and OUT file are different.
Using the HLSCOM Utility Command Dictionary HLS-process-name identifies the SNAX/HLS server process name. command is an HLSCOM command to be executed once the HLSCOM process has started. If commands are specified, HLSCOM suppresses the output of the banner and terminates after the last command. In particular, the IN file is not used. If no commands are specified, the banner line is printed and commands are read from the IN file until an end-of-file character or the EXIT command is read.
Using the HLSCOM Utility Command Dictionary Table 6-1.
Using the HLSCOM Utility Command Dictionary ABEND Command The ABEND command can only be issued from a SNAX/HLS communications session running on the same system as the SNAX/HLS server process. The ABEND command terminates the currently open SNAX/HLS primary process. The owner of the SNAX/HLS process, or $SUPER.SUPER, is the only user who can execute this command. This command allows system programmers to take a snapshot dump of the SNAX/HLS process for problem determination.
Using the HLSCOM Utility Command Dictionary ABORT Command The ABORT command can only be issued from a SNAX/HLS communications session running on the same system as the SNAX/HLS server process. The ABORT command allows the SNAX/HLS operator to terminate sessions forcibly. The effect of the command is the same as if the selected SNAX/HLS process performed a CLOSESESSION or HLS-DEALLOCATE verb. The owner of the SNAX/HLS process, or $SUPER.SUPER, is the only user that can execute this command.
Using the HLSCOM Utility Command Dictionary ALTER Command The ALTER command changes various SNAX/HLS parameters and options. ALTER [ keyword-and-value [, keyword-and-value] ...] keyword-and-value can be one of the following: BACKUPCPU integer adjusts the backup CPU. If integer is -1, the backup is stopped and not restarted; otherwise, integer must be in the range 0 through 15. BACKUPDEBUG yesno adjusts the BACKUPDEBUG option. The possible values TRUE, YES, ON, or SET all imply the option is turned on.
Using the HLSCOM Utility Command Dictionary EMS-2 collector-name assigns a new alternate collector number 2. collector-name must be the name of an EMS collector. EMS-3 collector-name assigns a new alternate collector number 3. collector-name must be the name of an EMS collector. LOG file-name assigns a new LOG file. file-name is typically the name of a spooler file or some other process (or omitted to stop logging). MSG file-name assigns a new message file.
Using the HLSCOM Utility Command Dictionary events are logged and/or sent to EMS. The text of messages produced on the log is not affected. Changing the RDT file introduces a new set of profiles to SNAX/HLS. Sessions already allocated are not affected. If the new RDT file cannot be allocated, the old RDT file remains in effect. Changing the backup CPU number from -1 (indicating that there is no backup) to a real value (in the range 0 through 15) causes the backup to be initiated.
Using the HLSCOM Utility Command Dictionary This command stops the current backup. After this command, SNAX/HLS is running without a backup. @ ALTER BACKUPCPU -1 This command attempts to bring up a backup in CPU 4.
Using the HLSCOM Utility Command Dictionary ASSUME Command The ASSUME command sets the default line-name for expansion of LU-specifier parameters in ABORT, INFO, LISTOPENS, STATUS, and TRACE commands. See the “Basic Components” discussion in this section for a description of LU-specifier. ASSUME [ line-name ] line-name is a valid line-name for the Tandem SNA access method used by SNAX/HLS. (For SNAX/XF this is a valid SNAX/XF line-name. For SNAX/CDF this is a valid SNAX/CDF process name.
Using the HLSCOM Utility Command Dictionary CMDSYS Command The CMDSYS command sets the default system for expansion of all file names (except OBEY file names). CMDSYS [ \system-name ] system-name is a system name. The initial setting is the default system used by the command interpreter when HLSCOM is started.
Using the HLSCOM Utility Command Dictionary CMDVOL Command The CMDVOL command sets the default volume and subvolume names for the expansion of all file names (except OBEY file names). CMDVOL [ $volume-name [ .subvolume-name ] ] [ subvolume-name ] volume-name is a volume name. The initial setting is the default volume used by the command interpreter when HLSCOM was started. If volume-name is omitted, the previous setting is used. subvolume-name is a subvolume name.
Using the HLSCOM Utility Command Dictionary ENV Command The ENV command displays the command defaults for file–name expansion and line-name expansion. ENV Example This command displays the CMDVOL and OBEYVOL file names. @ ENV Figure 6-2 shows an example of the ENV command. Figure 6-2. Example of ENV Display @env Cmd defaults: Obey defaults: Assumed line: 104705 Tandem Computers Incorporated $BIGD.PASO $BIGD.
Using the HLSCOM Utility Command Dictionary EXIT Command The EXIT command is processed in one of two ways: If HLSCOM is running interactively, the EXIT command stops the current HLSCOM. If HLSCOM is running noninteractively, the EXIT command exits the current OBEY file and reduces the nesting level of OBEY-file execution. If the EXIT command reduces the level to 0, the HLSCOM process is terminated. See the OBEY command for more information on levels.
Using the HLSCOM Utility Command Dictionary FC Command The FC command fixes the last interactive command entered.
Using the HLSCOM Utility Command Dictionary FILES Command The FILES command lists the files on a subvolume. FILES [ $volume-name [.subvolume-name] ] volume-name is a Tandem NonStop Kernel volume name. subvolume-name is a Tandem NonStop Kernel subvolume name.
Using the HLSCOM Utility Command Dictionary The following command displays the names of the files in the subvolume \DALLAS.$CRUDE.TEXAS: @FILES $CRUDE \DALLAS.$CRUDE.
Using the HLSCOM Utility Command Dictionary HELP Command The HELP command displays the syntax of HLSCOM commands. HELP [ topic ] topic specifies one of the following topics on which help is desired: command-name is the name of an HLSCOM command for which the syntax is to be displayed. is any parameter value that is enclosed in angle brackets (< >) when displayed by the command or ALL option. The angle brackets must be included.
Using the HLSCOM Utility Command Dictionary INFO Command The INFO command displays PROFILE and BIND-related information about a session. If the DETAIL option is used on this command, important fields of the current session BIND and additional PROFILE fields are displayed. INFO LU-specifier [ , DETAIL ] LU-specifier is a LU specifier in one of the standard forms. See the “Basic Components” discussion for information on LU-specifier. DETAIL If this phrase is appended, a more detailed listing is produced.
Using the HLSCOM Utility Command Dictionary Figure 6-3. Example of INFO Display @info $snal.* Session HS Open Profile Appl Max Xlate LMO ID Name Plrty Mode Name Name Req Ind -------------------------------------------------------------------------------3 $SNA1.#P1L1 PLU accept PATM3624 APPL 2 YES YES 4 $SNA1.#P1L2 PLU acquire P4DEFNP0 PRIM 2 YES NO @info $sna1.
Using the HLSCOM Utility Command Dictionary backup takeover occurred when the session was active, and that the application should deallocate such a session. Such a session should not be terminated using the ABORT command. HS Plrty Specifies the type of LU represented by this session ID. This field is either PLU (primary LU) or SLU (secondary LU). Open Mode Specifies the open mode of the session. This field is either accept or acquire.
Using the HLSCOM Utility Command Dictionary Session BIND parameters The application interface PROFILE shows the information listed below. For further details on these options, see “PROFILE Attributes” in Section 4, “Building the Resource Definition Table.” Accept Bind Specifies whether SNAX/HLS will use the BIND images carried in CINIT messages or replace it with the one defined in the RDT. (This option only exits if SNAX/CDF is being used as the Tandem SNA access method.
Using the HLSCOM Utility Command Dictionary Want Flow Control Specifies whether or not the application program is prepared to handle flowcontrol messages. Want SSCP Text Specifies whether or not the application program is prepared to receive SSCP-LU messages. Single FMH Specifies whether or not FMH continuation flags are to be honored.
Using the HLSCOM Utility Command Dictionary LISTOBJECTS Command The LISTOBJECTS command lists all the objects known to the subsystem. LISTOBJECTS [session] Consideration If the SESSION keyword is omitted, a list of all the objects known to the SNAX/HLS process is generated. This includes the SNAX/HLS process itself. If the SESSION keyword is included in the command, a list of the SESSION objects known to the SNAX/HLS process is generated.
Using the HLSCOM Utility Command Dictionary LISTOPENS Command The LISTOPENS command displays the openers of the SNAX/HLS process or the openers that have allocated or opened a set of sessions. LISTOPENS LISTOPENS LU-specifier LU-specifier is a LU specifier in one of the legal forms. See the “Basic Components” discussion for more information on LU-specifier.
Using the HLSCOM Utility Command Dictionary Figure 6-4. Example of LISTOPENS Display HLSCOM HLS Application (backup) $TALREQ PID 4,23 $ZNET SCP PID 2,12 HLS Application $TALREQ PID 3,34 SNAX/HLS $SNA1.#LU2 @listopens *.* Primary Backup Session Process CPU/ CPU/ Open Name Name FN PIN FN PIN Name -----------------------------------------------------$SNA1.#LU2 $TALREQ 3 3,34 3 4,23 #SNA1.
Using the HLSCOM Utility Command Dictionary Process Name Is name of the process that is associated with the indicated open. If the process is named, the process name is shown; if the process is not named, the process ID is displayed. If the open is associated with an Expand network process, the system name is also displayed. Primary FN and CPU/PIN Indicates the file number used by the primary process to access SNAX/HLS and the location of the primary process.
Using the HLSCOM Utility Command Dictionary LOG Command The LOG command directs a copy of the input commands and output generated by HLSCOM to a file. LOG directive directive is one of the following: TO file-name specifies the name of the file to receive the copy of the commands and output. This form of the command initiates the logging function. STOP closes the log file and stops all logging.
Using the HLSCOM Utility Command Dictionary OBEY Command The OBEY command causes commands to be read from a specified file. Such an OBEY file can itself contain OBEY command(s). The nesting of OBEY files can be up to three levels deep. Commands are read from the named file and processed until an end-of-file character, an EXIT command, a BREAK key, or an error is encountered.
Using the HLSCOM Utility Command Dictionary OBEYSYS Command The OBEYSYS command sets the default system for file–name expansion of files in OBEY commands. OBEYSYS [ \system-name ] \system-name is a system name. The initial setting is the system used by the command interpreter when HLSCOM is started. If system-name is omitted, OBEYSYS is cleared (there is no default), thus permitting reference to seven-character local device names that are too long to reference in network form.
Using the HLSCOM Utility Command Dictionary OBEYVOL Command The OBEYVOL command sets the default volume and subvolume for expansion of OBEY file names. OBEYVOL [ $volume-name [ .subvolume-name ] ] [ subvolume-name ] volume-name is a volume name. The initial setting is the default volume used by the command interpreter when HLSCOM is started. If volume is omitted, the previous setting is used. subvolume-name is a subvolume name.
Using the HLSCOM Utility Command Dictionary OPEN Command The OPEN command causes HLSCOM to direct all subsequent commands to the indicated instance of a SNAX/HLS server. OPEN [\system-name.]HLS-process-name \system-name is a valid Expand system name and is the location of the desired SNAX/HLS process. If no system-name is supplied, the local system is implied. HLS-process-name is the name of the SNAX/HLS process.
Using the HLSCOM Utility Command Dictionary PEEK Command The PEEK command displays internal configuration and resource utilization information for a given SNAX/HLS process. The display includes the following major sections: SNAX/HLS Identification Section. This section identifies the particular version of SNAX/HLS. Resource Definition Table Section. This section identifies the RDT database currently being used. Configuration Section.
Using the HLSCOM Utility Command Dictionary Figure 6-5. Example of PEEK Display @peek - - - - - - - - - - - - SNAX/HLS Identification Section - - - - - - - - - - - Process name: \WACO.$HLS Version: SNAX/HLS (T9089C20 15Mar91 C01AAY) COM-KRNL (T6562C20 30Jan91 S19AAK) - - - - - - - RDT file: Compiled by: - - - Resource Definition Table Section - - - - - - - - - $BIGD.PASO.
Using the HLSCOM Utility Command Dictionary Version Specifies the complete version banners of all software components inside SNAX/HLS, not HLSCOM. Resource Definition Table Section RDT File Specifies the file name of the current RDT database and the modification time stamp of the file. Compiled By Specifies the version banner of the RDT compiler that created the above RDT database. Configuration Section Program File Specifies the program file name and modification date of the SNAX/HLS process.
Using the HLSCOM Utility Command Dictionary Memory Swap Volume Specifies the name of the disk being used to swap the memory pool (extended storage). This is controlled by the SWAPVOL parameter at startup. Debug on Error Specifies the current value of the DEBUGONERROR switch. If the value YES is displayed, any internal error in SNAX/HLS causes the debug facility to be invoked. Primary CPU Specifies the CPU number currently assigned as the primary CPU.
Using the HLSCOM Utility Command Dictionary Customizer Section Is present only if the customization routines are enabled. Exits Enabled Lists those routines that are enabled by one or more of the following keywords: VERB-IN VERB-OUT SNAX-IN SNAX-OUT VRFY-BIND VRFY-STSN Buffer Size Specifies the amount of storage, in bytes, allocated for the use of the customization routines. CharacterSet Section This section is present if the default character mapping file $SYSTEM.SYSTEM.
Using the HLSCOM Utility Command Dictionary Trace File Shows the file name of the current trace file. State Shows the status (started or stopped) of the trace. Size Shows the number of pages assigned to the trace file. One page equals 2,048 bytes.
Using the HLSCOM Utility Command Dictionary Default Trace Flags Shows the activities selected for tracing with the INITIAL^TRACE configuration parameter. See Section 5 “Operating SNAX/HLS” for more information on this configuration parameter. If tracing has started (refer to the HLSCOM TRACE command), all activity specified here is traced for each session that becomes active.
Using the HLSCOM Utility Command Dictionary Allocated Contains two values that reflect the current and maximum number of bytes in use. The maximum value is counted since SNAX/HLS was last initiated, recovered, or the statistic was reset through the programmatic interface. Fragments Reflects the current and maximum number of fragments in the pool. The maximum value is counted since SNAX/HLS was last initiated, recovered, or the statistic was reset through the programmatic interface.
Using the HLSCOM Utility Command Dictionary QMSG Command The QMSG command queues a message on the receive queue of the specified sessions. The message is delivered with a DATA-TYPE-RECEIVED value of DT-INTERRUPT-REQUEST. The QMSG command can be used by an installation to broadcast site-specific information to SNAX/HLS applications. QMSG LU-specifier message-text LU-specifier is a LU specifier in one of the basic forms. See the “Basic Components” subsection for more information on the LU-specifier.
Using the HLSCOM Utility Command Dictionary STATUS Command The STATUS command provides summary information on the dynamic state of SNAX/HLS sessions. If the DETAIL option is used on this command, state and control information is included. STATUS LU-specifier [ , DETAIL ] LU-specifier is a LU specifier in one of the basic forms. See the “Basic Components” discussion for information on LU-specifier. DETAIL is a keyword to include extensive diagnostic information in the display.
Using the HLSCOM Utility Command Dictionary Summary Information Session ID Specifies the SNAX/HLS session ID for the displayed session name. This is the session ID returned to the SNAX/HLS application following execution of an OPEN-SESSION or HLS-ALLOCATE verb. Session Name Specifies the name of the LU being used by this session ID. When using *.* as the LU-specifier, the session name may appear in lower case.
Using the HLSCOM Utility Command Dictionary STARTED Indicates that the session is active. The detailed state information contained in the response to a STATUS LU-specifier, DETAIL request should be examined for further details. SUSP Indicates that the session is active, but no data traffic can flow. In SNA terms, this state might exist briefly at session startup, indicating that the BIND has flowed but the SDT has not yet flowed. STOPPING indicates that the session is being terminated.
Using the HLSCOM Utility Command Dictionary not_in_use The FSM is not initialized or is not used in this session. reset The FSM is reset and the session is not active. p_active A BIND RU has been sent or received by the SNAX/HLS server. The session is pending activation. active A BIND response has been sent or received by the SNAX/HLS server. The session is active. p_reset An UNBIND RU has been sent or received by the SNAX/HLS server. The response to UNBIND drives the session state to reset.
Using the HLSCOM Utility Command Dictionary not_in_use The FSM is not initialized or is not used in this session. reset The session is not in shutdown processing. p_shutc An SNA SHUTD RU has been sent or received by the SNAX/HLS server. The session is pending shutdown. quiesced The session is shut down. The SNA RU SHUTC has been sent or received by the SNAX/HLS server. Note that only the SLU session partner is quiesced and that the PLU session partner can still send messages.
Using the HLSCOM Utility Command Dictionary p_term_s A request to end the bracket has been sent. When the session partner accepts this request, the state changes to betb. Send/Rcv Controls send and receive modes for half-duplex data flows. If the BIND specifies non-full-duplex send and receive mode (byte 7, bits 0 and 1 nonzero), this FSM is active. The states displayed here are affected by the use of brackets. See the IBM SNA Format and Protocol Reference Manual for more information on this FSM.
Using the HLSCOM Utility Command Dictionary erp_send A negative response from the session partner has been sent or received. Error recovery processing (ERP) is in progress. The session is in SEND state, and no messages from the session partner can be received. erp_recv A negative response from the session partner has been sent or received. Error recovery processing (ERP) is in progress. The session is in RECEIVE state, and no messages to the session partner can be sent.
Using the HLSCOM Utility Command Dictionary Cbsm_Rsp_R Shows the state of the bracket state manager response received FSM. Despite the “Received” label, it belongs to the send portion of the session. It is employed to pass responses to the bracket state manager (see Bracket above) when a response is being received by the current chain, and the Chain_Recv FSM is in the BETC condition. The following values are displayed in this field: not_in_use The FSM is not initialized or is not used in this session.
Using the HLSCOM Utility Command Dictionary Chdx_Rsp_R This FSM controls the passing of negative responses to the send receive FSM (see Send/Rcv above). Despite the “Received” label, it belongs to the send portion of the session. This FSM passes responses only at end-of-chain. The field displays one of the following states: not_in_use The FSM is not initialized or is not used in this session. reset No user message (SNA chain) is being sent. inc A user message (SNA chain) is being sent.
Using the HLSCOM Utility Command Dictionary Chain_Send Tracks the state of the SNA chain send portion of the SNAX/HLS server. User messages are divided into maximum RU size segments by the SNAX/HLS server, unless LMO is in effect. As the SNAX/HLS server transmits the chain elements, this field shows the following states: not_in_use The FSM is not initialized or is not used in this session. betc The FSM is between chains. No user message is being transmitted. inc The FSM is in chain.
Using the HLSCOM Utility Command Dictionary QEC_Send Tracks the state of the quiesce protocol manager for inbound messages. Quiesce protocol allows either session partner to stop the flow of messages from the other session partner. This field can display one of the following states: not_in_use The FSM is not initialized or is not used in this session. reset A quiesce protocol exchange is not in progress. p_qc The quiesce protocol exchange is in progress; the QEC RU has been sent, and the QC RU is expected.
Using the HLSCOM Utility Command Dictionary EBCD_Send Enforces an optional send check that prevents the sending of messages carrying the CDI if the message also ends a transaction. The FSM can have the following states: not_in_use The FSM is not initialized or is not used in this session. reset There is no current user message in progress. inc There is a current user message in progress.
Using the HLSCOM Utility Command Dictionary SBI_Send Enforces the stop bracket initiation protocol for the sender. Although no protocol currently supported by the SNAX/HLS server uses this facility, it is included for completeness. The FSM can have the following states: not_in_use The FSM is not initialized or is not used in this session. reset There are no stop bracket functions outstanding. P_nobb An SBI command has been issued, and the half-session is awaiting the receipt of a BIS command.
Using the HLSCOM Utility Command Dictionary IMM_RQ_Send Enforces the immediate request protocol on behalf of the sender. This protocol requires that no requests be sent while a previously sent definite-response request is still outstanding. The information displayed is: not_in_use The FSM is not initialized or is not used in this session. reset There are no unacknowledged DR requests outstanding. owed A DR request has been sent; a response is owed. inc A chain is being sent.
Using the HLSCOM Utility Command Dictionary IMM_RQ_Recv Enforces the immediate request protocol on behalf of the receiver. This protocol requires that no requests be received while a previously received definite-response request is still outstanding. The information displayed is: not_in_use The FSM is not initialized or is not used in this session. reset There are no unacknowledged DR requests outstanding. owed A DR request has been received; this half-session owes a response.
Using the HLSCOM Utility Command Dictionary Control Information Allocators Specifies a count of the number of accessors that have allocated this SNAX/HLS LU. If the application uses server links (that is, opens with the form $hls-name), then each server link from a given process is deemed an accessor and is reflected in this count. Openers Specifies a count of the number of accessors that have opened a session with this SNAX/HLS LU.
Using the HLSCOM Utility Command Dictionary SYSTEM Command The SYSTEM command is used to set the default system for all file–name expansions. The SYSTEM command is equivalent to entering a CMDSYS command and an OBEYSYS command, both with the same system-name specification. SYSTEM [ \system-name ] \system-name is a system name. The initial setting is the default system name used by the command interpreter when HLSCOM is started.
Using the HLSCOM Utility Command Dictionary TRACE Command The TRACE command specifies tracing operations. Use this command to do the following: Designate the file that is to hold the trace Designate the sessions that are to be traced and what types of trace to use Eliminate selected sessions from the trace Start the trace Stop the trace TRACE { { { { { DISABLE LU-specifier } ENABLE LU-specifier [,TYPE type [,type]...
Using the HLSCOM Utility Command Dictionary START directs the SNAX/HLS server to open the trace file and begin collecting trace records. STOP directs the SNAX/HLS server to close the trace file. Considerations The status of trace activity for each SNAX/HLS session is kept in a special header of the trace file called the entity trace table (ETT). The trace file must be open and trace must be active before elements can be added to the ETT.
Using the HLSCOM Utility Command Dictionary This command adds the SNAX/HLS session #LU4 (qualified with the current default line-name set by the ASSUME command) to the ETT. All calls to the data flow control layer of SNAX/HLS are traced. @ TRACE ENABLE #LU4,TYPE D This command adds all SNAX/HLS sessions on line-name $SNA2 to the ETT. The trace information saved includes all verb interfaces and all calls to the logical unit service manager in SNAX/HLS. @ TRACE ENABLE $SNA2.
Using the HLSCOM Utility Command Dictionary VERSION Command The VERSION command causes HLSCOM to display its version banner. VERSION Consideration The banner line consists of: 1. The product name—SNAX-HLS/HLSCOM 2. The product number—T9089onn—where o is the release level (for example, A, B, C) and nn is the interim level (for example, 00, 10, 25) 3. The object release date in DDMMMYY format 4.
Using the HLSCOM Utility Command Dictionary VOLUME Command The VOLUME command sets the default volume and subvolume for expansion of all file names. The VOLUME command is equivalent to entering a CMDVOL command and an OBEYVOL command, both with the same volume and subvolume specifications. VOLUME [ $volume-name [ .subvolume-name ] ] [ subvolume-name ] volume-name is a volume name. The initial setting is the default volume used by the command interpreter when HLSCOM was started.
Using the HLSCOM Utility Command Dictionary (This page left intentionally blank) 6–66 104705 Tandem Computers Incorporated
7 Interpreting SNA Protocol This section contains miscellaneous notes on how SNAX/HLS uses the SNA protocol. The presentation presumes a fairly detailed knowledge of SNA. For more information on this subject, consult the SNA references listed in “About This Manual.” Response Protocols SNAX/HLS uses the BIND image to determine which response protocol to use. This determination is modified by the application program's use of the NOTIFY-IND modifier on the SEND-DATA and SEND-AND-RECEIVE-DATA verbs.
Interpreting SNA Protocol Temporary UNBIND Temporary UNBIND When SNAX/HLS receives an UNBIND request (with type code 02), it does not terminate the session with respect to the application. This can occur when beginning a TSO session. SNAX/HLS keeps all resources allocated while anticipating the promised BIND command. If the application has enabled BIND and CINIT messages, it receives two such messages (one for the initial BIND and one for the second BIND).
Interpreting SNA Protocol Treatment of SIG (SIGNAL) Requests Responses Owed The IBM SNA Format and Protocol Reference Manual: Architecture Logic defines a procedure named RESPONSES_OWED on page 5-43. This procedure is used to disallow sending of data in half-duplex modes if the half-session has received but not yet responded to a request.
Interpreting SNA Protocol Pacing Throughput Considerations Pacing-Throughput Considerations SNAX/HLS supports pacing. When planning high-throughput sessions, you may want to specify a large pacing window size for the flow of data into SNAX/HLS. To allow for efficient line utilization, SNAX/HLS sends the pacing response (assuming that the pacing indicator has arrived) as soon as it is specified by the pacing-window size attribute.
Appendix A Table of RU Sizes Table A-1 shows the range of possible RU sizes in bytes. Use this table to obtain the actual RU size. Table A-1.
Table of RU Sizes (This page left intentionally blank) A–2 104705 Tandem Computers Incorporated
Appendix B HLSCOM Error Messages This appendix contains HLSCOM error messages. In general, the HLSCOM error messages that report SPI or token-in-error messages occur when your command was syntactically correct, its parameters passed all validity checks, but through a typing mistake or some other error, the command indicated the wrong object. The error messages listed in Table B-1 are SPI messages that could have been caused by a processor switch, a process failure, or an internal programming error.
HLSCOM Error Messages Table B-1.
HLSCOM Error Messages No backup CPU is assigned Cause. No backup CPU was available to take over after an ABEND command. Effect. A backup does not take over after the abend. Recovery. Specify a backup CPU, using the ALTER BACKUPCPU command. HLSCOM System-Level Error Messages The following error messages indicate that HLSCOM has encountered problems with the environment, such as the SPI interface, RDT files, and TRACE files: Command command not supported Cause.
HLSCOM Error Messages Failure accessing trace file Cause. The SNAX/HLS server could not access the trace file because of a file-system error. Effect. The command fails. Recovery. See if the trace file exists and check its security. When you have corrected the situation, reissue the command. Invalid duplicate use of token token Cause. The HLSCOM program used the same token twice in the same command where the command does not allow this token to be used twice in the same command. Effect. The command fails.
HLSCOM Error Messages No server currently open Cause. There is no HLSOBJ server open. Effect. The command fails. Recovery. Issue the OPEN command to open a server. No subordinates were found Cause. HLSCOM attempted to access a set of nonexistent subordinate objects. Effect. The command fails. Recovery. Correct the object name in your command and reissue the command. No trace file assigned Cause. You did not designate the trace file using a TRACE FILE command, before starting the trace. Effect.
HLSCOM Error Messages SSID invalid Cause. The HLSCOM program attempted to access a subsystem by using an invalid subsystem ID. Effect. The command fails. Recovery. Correct the command and reissue it. The use of token token is invalid Cause. HLSCOM attempted to use token where a token of another type was expected. Effect. The command fails. Recovery. Retry the command. If the error persists, consult your Tandem analyst. Token token must have a specific value Cause.
HLSCOM Error Messages Token token is required and is missing Cause. The HLSCOM program did not include all tokens required for a command. Effect. The command fails. Recovery. Retry the command. If the error persists, consult your Tandem analyst. Tokens token1 and token2 have conflicting values Cause. The HLSCOM program encountered two tokens whose values should have been in agreement, but were not. Effect. The command fails. Recovery. Retry the command. If the error persists, consult your Tandem analyst.
HLSCOM Error Messages (This page left intentionally blank) B–8 104705 Tandem Computers Incorporated
Appendix C HLSRDT Error Messages The following error messages are generated by the HLSRDT program. An object by that name does not exist Cause. You have referenced an object that has not been added. Effect. The command fails. Recovery. Correct any wrong names, or misspellings of the object name, and reissue the command. An object of the same name already exists Cause. You attempted to add an object with a name that already exists. Effect. The command fails. Recovery.
HLSRDT Error Messages Hex string too long Cause. The hexadecimal string you entered is too long. Effect. The command fails. Recovery. Correct the hexadecimal string and reissue the command. Invalid character in hex string Cause. You entered an invalid digit in a hexadecimal string. The valid digits are 0 through 9 and A through F (the letters can be in uppercase or lowercase). Effect. The command fails. Recovery. Correct the hexadecimal string and reissue the command. No profiles defined Cause.
Appendix D Supplemental Information for D-Series Systems This appendix provides specific information about D-series SNAX/HLS relevant to the SNAX/HLS Configuration and Control Manual.
Supplemental Information for D-Series Systems D-Series and C-Series Networking Restrictions D-Series and C-Series Networking Restrictions D-series SNAX/HLS follows the rules and conventions that govern network communication and compatibility between D-series software, C-series software, and Bseries software. D-series SNAX/HLS runs only on the D-series operating system. However, D-series SNAX/HLS processes running at a low PIN can directly communicate with C-series systems.
Supplemental Information for D-Series Systems Process, File, Device, and Volume Names Process, File, Device, and Volume Names D-series SNAX/HLS supports the following D-series-operating-system-naming conventions: Remote process names of up to six characters (including a $) Remote file, device, and volume names of up to eight characters (including a $) D-series SNAX/HLS does not support process file names with a sequence number.
Supplemental Information for D-Series Systems Process, File, Device, and Volume Names (This D–4 page left intentionally blank) 104705 Tandem Computers Incorporated
Glossary This glossary defines terms used and referred to in SNA and SNAX/HLS. Several definitions have been borrowed from IBM’s Dictionary of Computing (SC20–1699) and IBM’s Network Program Products: General Information (GC30–3350). $SSCP. Process name of the SNAX/XF Service Manager. ANSI. American National Standards Institute. application prototyping and simulation. A SNAX/HLS tool used by software developers to quickly and easily determine how their applications work. APS.
Glossary communication interface unit (CIU ). A hardware unit that, together with the SNAXLink software and the CAU, provides a direct channel link between a Tandem system and an IBM system. The CIU controller attaches directly to the Tandem processor through a standard I/O card slot. Communications Management Interface (CMI). A Tandem subsystem that is used for configuring and controlling communications subsystems such as SNAX/XF. See also Subsystem Control Facility. configuration.
Glossary DTE. See data–terminal equipment. EIO. See execute I/O. EMS. See event management service. event. An event is an uncontrolled or unplanned transmission. Critical events are those conditions that applications cannot handle and that cause processes or even sessions to terminate. Noncritical events are conditions that applications can handle and from which they can recover. Action events are those events that require operator intervention. Event Management Service.
Glossary HLSTAP. Trace Analysis Program for SNAX/HLS. HLSTAP formats SNAX/HLS requests and responses in terms that do not require a detailed understanding of SNAX/HLS. HLSRDT. Constructs the resource definition table (RDT) for SNAX/HLS. The RDT is the configuration database for SNAX/HLS. Each RDT PROFILE contains the required SNA–specific information necessary to configure and initiate a session. This information includes such SNA parameters as the BIND and INIT–SELF. host.
Glossary microcode. A code representing the instructions of an instruction set that is implemented in a part of storage that is not program–addressable. MICROCODE_FILES paragraph. A paragraph within the SYSGEN configuration file that is used to indicate the location of the downloadable microcode for controllers and other devices. NAU. Network addressable unit. NCP. Network control program. network. A group of interconnected computer systems and devices, and the hardware and software used to connect them.
Glossary PERIPHERALS paragraph. A paragraph within the SYSGEN configuration file that is used to define the SNAX/XF $SSCP process (Service Manager) and the SNAX/XF lines. physical unit. That part of a device (hardware or software) that provides control functions for its own node and for the other less intelligent device nodes attached to the PU. pipelining. A session is pipelined if it can be accessed by more than one requester.
Glossary session. In SNA, a temporary logical connection between two NAUs for the purpose of exchanging data and control information in accordance with ground rules that have been agreed upon for that exchange. A session can be activated, tailored to provide various protocols, and deactivated, as requested. session passthrough. A SNAX/XF feature that allows the SNA host to control SNA devices on Tandem NonStop systems as if they were directly connected to the host. site update tape (SUT).
Glossary SSCP–SSCP session. In SNA, a session between the SSCP in one domain and the SSCP in another domain. An SSCP–SSCP session is used to initiate and terminate cross– domain LU–LU sessions. static passthrough. A passthrough mode that allows SLUs connected to a Tandem system to take the initiative in establishing sessions with host application programs. With static passthrough, the host SSCP can send USS messages to devices connected to a Tandem system. subsystem.
Glossary Systems Network Architecture Communications Services/Extended Facility (SNAX/XF). A Tandem software product that provides a gateway between Tandem NonStop systems and SNA systems and devices. With SNAX/XF, Tandem systems can function as fully integrated components of an SNA network. SNAX/XF allows SNA devices attached to a NonStop system either directly or through a switched line to use Tandem applications.
Glossary (This page left intentionally blank) Glossary–10 104705 Tandem Computers Incorporated
Index 0813 Reject with NO-RTR 2-22 0814 Reject with AUTO 2-22 USER 2-22 327x-type devices 2-2 A Application designer,described 1-4 Application development,personnel involved in 1-4 Application environment, planning 2-2, 2-15 Application interface 1-5 Application Prototyping and Simulation,See also APS 1-5 APS function of 1-5 prototyping and simulation 1-11 ASCII, translating 2-6 AUTO, Reject with 0814 2-22 B BIND attributes 4-29, 4-37/40 BIND images avoid unlimited RU sizes 2-5 BIND, in RDT database 4-1 BIN
Index Command interface, HLSCOM 6-1 Command interface,HLSCOM 1-11 Comment records,in HLSMSGS file 3-7 Comments, in HLSRDT commands 4-3 Communications links, planning 2-5 Compression indicator, of data 2-9 Configuration planning 2-5 CONVERT-ERROR-CODE verb, use of 2-29 Copybooks,use of 2-24 Correlation tables, SNAX/HLS 7-2 D Data formatting,requirements 1-4 Data presentation,requirements 1-4 Data,compression 2-9 Data-transfer verbs,list of 1-10 DATA-TYPE-RECEIVED indicator 2-24 Device data streams, planning
Index Flow control messages, SNAX/HLS encoding 2-21 Flow control, SNAX/HLS treatment of 7-2 FLOW-CONTROL-WANTED 2-21 Flows example of 1-7 highlights of 1-7 FM profile selection 2-7 FM usage 2-10 FM usage, in session binds 2-7 FMHs non-standard convention 2-3 used in gateways 2-4 used with devices 2-3 Full-duplex communication, recommended for gateways 2-5 Function management headers (FMHs), used with devices 2-3 G Gateway system planning 2-3 Gateways and multiple SDLC links 2-5 special device data streams
Index HLSCOM commands (continued) FC 6-17 FILES 6-18 HELP 6-20 INFO 6-21 LISTOPENS 6-26, 6-27 LOG 6-30 OBEY 6-31 OBEYSYS 6-32 OBEYVOL 6-33 OPEN 6-34 PEEK 6-35 QMSG 6-43 STATUS 6-44 summary of 6-4 SYSTEM 6-60 TRACE 6-61 VERSION 6-64 VOLUME 6-65 HLSCOM error conflicting token values B-7 empty response B-3 failure accessing trace file B-4 invalid subsystem ID B-6 invalid token length B-6 invalid token value B-6 invalid use of token B-6 missing object types B-4 missing subordinate objects B-5 no backup B-3 no
Index HLSCOM,function of 1-5 HLSDDS source module 2-24 HLSDDT source module 2-24 HLSMSGS file format of 3-7 installing 3-5 modifying 3-6 HLSMSGS file, and RETRY-ACTION-CODE Values 2-30 HLSMSGS, security 3-5 HLSOBJ command syntax 5-2 HLSOBJ, programmatic startup 5-14 HLSOBJ, security 3-5 HLSOBJ,function of 1-5 HLSRDT attributes 4-29, 4-46 command use 4-3 commands 4-4, 4-28 ADD 4-5 CMDSYS 4-6 CMDVOL 4-7 ENV 4-9 EXIT 4-10 FC 4-11 FILES 4-12 HELP 4-14 HLSRDT 4-23 INFO 4-16 LOG 4-17 OBEY 4-18 OBEYSYS 4-19 OBEYV
Index HLSRDT (continued) RUN command 4-1 session example 4-46 HLSRDT command DELETE 4-8 SHOW 4-24 HLSRDT error C-1 BIND missing C-1 invalid character in hexadecimal string C-2 invalid hexadecimal string length C-2 invalid string length C-2 missing object C-1 object already exists C-1 PROFILEs not defined C-2 unnamed object C-2 HLSRUN macro, invoking 3-9 HLSRUN, to configure PATHWAY 3-9 HLSTAP function of 1-5 trace analysis program 1-12 HLSTAP, installing 3-5 I IBM host application, gateways 2-3 IMS,and DR
Index L Lines configuration planning 2-5 options for switched 2-6 Log facility 5-12 LU names, language support 2-16 LU naming run-time 2-15 LUs naming schemes 2-1 pipelined 2-22 SCOBOLX naming conventions 2-32 M Message volume 5-14 Modem eliminators,cost savings 2-5 Modes, send or receive 2-31 Multiple requesters,and pipelined LUs 2-22 N Naming conventions,SCOBOLX 2-32 NO-RTR, Reject with 0813 2-22 NonStop considerations 2-23 O Options, selecting PROFILE 2-20 P Pacing considerations, throughput 7-4 Pacing
Index Planning SNAX/HLS application partner requirements 2-2 SNAX/HLS applications 2-1 PLU network name 2-15 Presentation services profile 2-14 Primary LU network name 2-15 Products,Tandem and SNAX/HLS 1-2 PROFILE attributes 4-29, 4-36 PROFILE naming,run-time 2-15 PROFILE options,selecting 2-20 PROFILE, in RDT database 4-1 Programming standards,planning for 2-2, 2-24 Prototyping using APS 1-11 PS profile 2-14 Purging chains 7-2 PUs, and configuration planning 2-5 R RDT BIND 1-10 creating a file 1-11 descri
Index Return codes,handling when not RC-OK 2-29 RETURN-CODE field,purpose 1-5 RTR message, SNAX/HLS treatment of 7-2 RU size table of encoding A-1 RU size, table of encoding 2-14 RU tests, SNAX/HLS 7-2 RUN command, HLSCOM 6-3 RUN HLSOBJ command,syntax 5-2 Run-time LU naming 2-15 S SAVEABEND,must enable INSPECT SAVEABEND 5-6 SCOBOLX integer variables 2-34 naming conventions 2-32 SCOBOLX copybook 2-24 SCOBOLX requesters,and SNAX/HLS 2-16 SDLC links, multiple 2-5 Security, for SNAX/HLS and files 3-5 Send mode
Index SNA requests special 2-3 special with gateways 2-4 SNA terms,correspondence with SNAX/HLS terms 1-6 SNA3270 interface,relationship to SNAX/HLS 1-2 SNALU interface 1-3 SNALU interface,relationship to SNAX/HLS 1-2 SNAX requirements, planning for 2-1, 2-4 SNAX/HLS components 1-5 self-configuring characteristics 1-6 server process 1-7 terms correspondence with SNA terms 1-6 SNAX/HLS application, partner requirements,planning for 2-2 SNAX/HLS command interface, HLSCOM 6-1 Special devices data streams for
Index Two-phase commit, not interpreted by SNAX/HLS 2-9 TWS communication, evaluation 2-5 U UNBIND, temporary 7-2 USER, Reject with 0814 2-22 User-controlled responses, PROFILE option 2-21 USER-RESPONSES 2-21 V Verbs choice of names 1-6 data-transfer list of 1-10 delivery and replies 1-5 in application interface 1-5 miscellaneous 1-9 session control 1-9 session discontinuation 1-9 session establishment 1-9 VTAM LOGMODE entries, for gateways 2-4 VTAM/NCP SDLC links, configured with SNAX 2-4 W WANT-BIND-DATA
