Networking and Data Communications Library SNAX/HLS Application Programming Manual Abstract SNAX/HLS provides a general, high-level interface for application programs to communicate with intelligent SNA devices and software products Part Number 104707 Edition Second Published December 1994 Product Version SNAX/HLS D30 Release ID Supported Releases D30 This manual supports D30.00 and all subsequent releases until otherwise indicated in a new edition.
Document History Edition Part Number Product Version Earliest Supported Release Published First Update 1 Second 064393 068531 104707 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 This edition of the SNAX/HLS Application Programming Manual (part number 104707) incorporates many changes and additions to the previous version (part number 068531). All changes and additions are indicated by change bars. The major changes are as follows: The Guardian 90 operating system is now called the Tandem NonStop Kernel. In Section 7, “Customization,” there are additions to the SNAXHLS^USEREXIT^VERB^BLOCK structure.
New and Changed Information (This page left intentionally blank) iv 104707 Tandem Computers Incorporated
Contents About This Manual xi Notation Conventions Section 1 xiii SNAX/HLS Programming Standards HLSDDS-SCOBOLX Copybook 1-1 Server and Terminal Interfaces 1-8 TAL Applications 1-13 HLSDDT-TAL Copybook 1-13 Application-to-SNAX/HLS Interfacing Other Languages Section 2 1-20 Connection Types Server Connection Section 3 1-17 2-1 Sessions Allocating the Half-Session 3-1 Opening Communication With the Session Partner Exchanging Data With the Session Partner 3-2 Deallocating the Half-Session 3-2 Alloc
Contents Standard Verb Formats 4-5 Request Format 4-5 Reply Format 4-6 Section 5 SNAX/HLS Verbs CLOSE-SESSION Verb 5-2 CONVERT-ERROR-CODE Verb GET-ATTRIBUTES Verb HLS-ALLOCATE Verb HLS-CLOSE Verb 5-7 5-12 5-17 HLS-DEALLOCATE Verb 5-22 HLS-FLOW-CONTROL Verb HLS-OPEN Verb 5-4 5-25 5-32 HLS-RESPOND Verb 5-43 OPEN-SESSION Verb 5-47 PREPARE-TO-CLOSE Verb 5-53 RECEIVE-CONTROL Verb 5-58 RECEIVE-CONTROL-WAIT Verb REVEIVE-DATA Verb 5-80 REQUEST-SEND-STATE Verb 5-92 SEND-AND-RECEIVE-DATA Ver
Contents Aloc: HLS-ALLOCATE Verb (SF2) Clos: HLS-CLOSE Verb (SF4) 6-10 6-13 CS: CLOSE-SESSION Verb (F3) 6-16 Deal: HLS-DEALLOCATE Verb (SF5) Exit: Exit APS (F16) 6-20 6-18 Flow: HLS-FLOW-CONTROL Verb (SF7) 6-21 GA: GET-ATTRIBUTES Verb (F10) 6-23 Hex: Translate to Hexadecimal (F14) 6-26 Open: HLS-OPEN Verb (SF3) 6-27 OS: OPEN-SESSION Verb (F1) 6-31 PC: PREPARE-TO-CLOSE Verb 6-35 Prnt: Print Screen (F13) 6-37 RC: RECEIVE-CONTROL Verb (F4) 6-38 RCWT: RECEIVE-CONTROL-WAIT Verb (SF8) RD: RECEIV
Contents HLS-CALL-USER Verb 7-4 Data Structures 7-9 The SNAXHLS^USEREXIT^IN^BLOCK Structure 7-9 The SNAXHLS^USEREXIT^OUT^BLOCK Structure 7-10 The SNAXHLS^USEREXIT^VERB^BLOCK Structure 7-11 The BIND^TEMPLATE Structure 7-13 The STSN^TEMPLATE Structure 7-13 Accessing Storage 7-14 Procedure Specifications 7-15 The USEREXIT^ENABLE Routine 7-15 The USEREXIT^VERB^IN Routine 7-16 The USEREXIT^VERB^OUT Routine 7-17 The USEREXIT^SNAX^IN Routine 7-19 The USEREXIT^SNAX^OUT Routine 7-20 The USEREXIT^VRFY^BIND^ 7-22 T
Contents Figure 5-1. Example of CONVERT-ERROR-CODE Figure 5-2. Example of PLU HLS-CLOSE 5-21 Figure 5-3. Example of SLU HLS-CLOSE 5-21 Figure 5-4 . Example of HLS-FLOW-CONTROL (SM) 5-30 Figure 5-5. Example of HLS-FLOW-CONTROL (RT) 5-31 Figure 5-6. Example of HLS-OPEN Figure 5-7. Example of Primary Acquire Figure 5-8. Example of Primary Accept Figure 5-9. Example of Secondary Acquire 5-42 Figure 5-10. Example of Secondary Accept 5-42 Figure 5-11.
Contents x Figure 6-10. GET-ATTRIBUTES Screen (Format 2) 6-24 Figure 6-11. HLS-OPEN Screen Figure 6-12. OPEN-SESSION Screen Figure 6-13. PREPARE-TO-CLOSE Request Screen Figure 6-14. RECEIVE-CONTROL Screen Figure 6-15. RECEIVE-DATA Screen Figure 6-16. HLS-RESPOND Screen Figure 6-17. SET-ATTRIBUTES Request Screen Figure 6-18. SEND-DATA Request Screen Figure 6-19. SEND-STATUS Request Screen Figure 6-20. REQUEST-SEND-STATE Request Screen Figure 6-21.
About This Manual SNAX High-Level Support (SNAX/HLS) software provides a simple application programming interface for Tandem application programs to communicate with Systems Network Architecture (SNA) devices and SNA host software. Audience This manual is for individuals writing Tandem application programs that use SNAX/HLS to communicate with SNA devices or SNA host software.
About This Manual Organization (This page left intentionally blank) xii 104707 Tandem Computers Incorporated
Notation Conventions The following list summarizes the conventions for syntax presentation in this manual. Notation Meaning UPPERCASE LETTERS lowercase italic letters Brackets [ ] Uppercase letters represent keywords and reserved words; enter these items exactly as shown. Lowercase italic letters represent variable items that you supply. Braces { } Vertical line | Ellipsis ... Percent sign % I and O Spaces Punctuation Brackets enclose optional syntax items.
Notation Conventions (This page left intentionally blank) xiv 104707 Tandem Computers Incorporated
1 SNAX/HLS Programming Standards Although application programs written in any Tandem language can communicate with SNAX/HLS, the most support is offered for those written in SCOBOLX and TAL. The following subsections discuss programming standards and conventions relative to SCOBOLX, TAL, and other languages. SCOBOLX Relative to a SCOBOLX application program, SNAX/HLS can be considered either a Applications server or a device.
SNAX/HLS Programming Standards SCOBOLX Applications By judicious use of these variables, your program can avoid specific numeric references to SNAX/HLS data types when analyzing the responses to receive type verbs RECEIVE-DATA, RECEIVE-CONTROL, or RECEIVE-CONTROL-WAIT. Section RETURN-CODE-DEFINITIONS Use the following statement within the working storage section of the data division to include the RETURN-CODE-DEFINITIONS section of the copybook in your program: copy RETURN-CODE-DEFINITIONS of HLSDDS.
SNAX/HLS Programming Standards SCOBOLX Applications Table 1-1.
SNAX/HLS Programming Standards SCOBOLX Applications A verb reply contains the standard reply header (REPLY-HEADER) followed by the building block(s) needed for the given verb reply, as shown in Table 1-2. Table 1-2.
SNAX/HLS Programming Standards SCOBOLX Applications Request and Reply Definitions The HLSDDS copybook includes definitions of every request and reply used for the Pathway IDS (Intelligent Device Support) interface. Section names are derived by appending the letters -REQUEST or -REPLY to verb names. For example, the copybook statements provided for the request and the reply for the OPEN-SESSION verb are: ?SECTION OPEN-SESSION-REQUEST ... ?SECTION OPEN-SESSION-REPLY ...
SNAX/HLS Programming Standards SCOBOLX Applications This section defines the names (not the values) of the various SNAX/HLS verb completion codes. Its primary use is to enable your program to convert return-code values into the standard name (without the RC- prefix and with all hyphens converted to underscores). The data structure itself is defined as follows: ?SECTION RC-NAME-TAB 01 RC-NAME-TAB. 02 filler pic X(23) value "ok". ... 02 filler pic X(23) value "session_not_allocated".
SNAX/HLS Programming Standards SCOBOLX Applications Note, in particular, how the example tests the value for legal ranges. The variables VERB-FIRST and VERB-LAST are defined with the other verb values above. IF VERB-CODE IS NOT < VERB-CODE IS NOT > SUBTRACT VERB-FIRST MOVE VERB-NAME-LIST VERB-FIRST AND VERB-LAST FROM VERB-CODE GIVING ws-index (ws-index) TO Name-of-verb-code.
SNAX/HLS Programming Standards SCOBOLX Applications Server and terminal Interfaces The server and terminal interfaces are described below. Server Interface If SNAX/HLS is accessed through the server interface, you issue requests to SNAX/HLS using the SEND statement. For example, to issue an OPEN-SESSION request, your program might look as follows: (Statements to prepare the text in the OPEN-SESSION-REQUEST structure) MOVE verb-open-session TO verb-code OF request-header.
SNAX/HLS Programming Standards SCOBOLX Applications When an unsolicited message arrives and your SEND MESSAGE statement includes the ESCAPE ON UNSOLICITED MESSAGE clause, or when a timeout occurs because your SEND MESSAGE statement includes the TIMEOUT clause, Pathway’s TCP responds by sending an interrupt signal (CONTROL-26) to SNAX/HLS.
SNAX/HLS Programming Standards SCOBOLX Applications Normal termination occurs when SNAX/HLS completes your operation, independent from the occurrence of any timeout or unsolicited message arrival. There might have been a timeout or a message arrival, but SNAX/HLS terminated the operation based upon conditions outside these events. In this case, your SEND MESSAGE operation completes just as if these escape clauses were not present.
SNAX/HLS Programming Standards SCOBOLX Applications The WORKING-STORAGE section of the program should include the following definitions: COPY send-and-receive-data-request OF hlsdds. 02 send-length PIC 9(4) COMP. 02 send-text PIC X OCCURS 0 TO 397 TIMES DEPENDING ON send-length OF send-and-receive-data-request. COPY COPY COPY 02 02 77 receive-data-request OF hlsdds. send-data-reply OF hlsdds. receive-data-reply OF hlsdds. recv-length PIC 9(4) COMP.
SNAX/HLS Programming Standards SCOBOLX Applications wait-for-completion. MOVE verb-receive-data TO verb-code OF receive-data-request. SEND MESSAGE receive-data-request REPLY CODE FIELD IS verb-code OF receive-data-reply CODE verb-send-data YIELDS send-data-reply CODE verb-receive-data YIELDS receive-data-reply ESCAPE ON UNSOLICITED MESSAGE TIMEOUT 20 ON ERROR GOTO something-happened. GOTO normal-ending. reply-was-send-data. PERFORM analyze-data-just-sent.
SNAX/HLS Programming Standards SCOBOLX Applications Note how the definitions in WORKING-STORAGE are constructed to create data structures containing the entire bodies of the verbs. The variable-length portions are appended to the definitions by application-defined text. In this way, the actual RUsize limits, which are application-dependent, are under your control.
SNAX/HLS Programming Standards SCOBOLX Applications Section RETURN^CODE^DEFINITIONS Use the following statement to include the RETURN^CODE^DEFINITIONS section of the copybook in your program: ?source HLSDDT( return^code^definitions ) It provides the basic value definitions for the return codes used by SNAX/HLS. For example, the code for RC-OK is defined by: LITERAL rc^ok = 0; All return codes are literals named RC^xxx. The lowest value used for return codes is RC^^FIRST, and the highest value is RC^^LAST.
SNAX/HLS Programming Standards SCOBOLX Applications ?source HLSDDT(rc^nams) This section defines the names (not the values) of the various SNAX/HLS verb return codes. Its primary use is to enable your program to convert return-code values into the standard name (without the RC^ prefix and with all circumflexes [^] converted to underscores). The data structure itself is defined as a P-relative string, as follows: ?SECTION RC^NAMS STRING RC^^NAMS = 'P' := [ "ok .....
SNAX/HLS Programming Standards SCOBOLX Applications The following fragment of code illustrates how your program might extract the characters, given a verb-code value of vb. Note, in particular, how the example tests the value for legal ranges and uses the string width as defined by the literal.
SNAX/HLS Programming Standards SCOBOLX Applications Note that Desired^Answer, (the recipient of the string) should be declared with the capability of holding a string of the size defined by the string width literal. Note Application-to-SNAX/HLS Interfacing Since LITERAL DT^WIDTH is not in the DT^NAMS section, you must source section DATA^TYPE^DEFINITIONS for this example to work.
SNAX/HLS Programming Standards SCOBOLX Applications manner in which the request and the reply are connected. When you use the queued completion mode, the reply with RC-FORTHCOMING is returned to you, and the actual completion arrives later. When you use the interrupt facility, the reply with file-system reply code 189 is returned to you and the actual completion arrives later.
SNAX/HLS Programming Standards SCOBOLX Applications If a WRITEREAD you interrupted completes with 0, its work was already complete. If a WRITEREAD you interrupted completes with 187, you have interrupted a RECEIVE-DATA or RECEIVE-CONTROL-WAIT , and there are no outstanding activities on the session for which you are responsible.
SNAX/HLS Programming Standards Other Languagues WRITEREAD Procedure The read count specifying the space allocated for the response should be large enough to contain the response. It must be at least 12 bytes to contain the response header and large enough to contain the response to the verb being issued. Failure to comply with this will result in a file-system error. The error will vary with the verb.
2 Connection Types Communication between a user application program and SNAX/HLS is through the standard interprocess communication protocol. The application program establishes the connection using an OPEN request to the Tandem NonStop Kernel, specifying as a file-name the name of the SNAX/HLS server or the LU name. The Tandem NonStop Kernel returns a logical file number, which is used in all I/O requests dealing with the connection opened.
Connection Types Server Connection (This page left intentionally blank) 2–2 104707 Tandem Computers Incorporated
3 Sessions A session in SNAX/HLS is the vehicle through which partners exchange data and controls. A half–session refers to the session as seen by one of the partners. A typical session goes through the following sequence of events: 1. Allocating the half–session 2. Opening communication with the session partner 3. Exchanging data with session partner 4. Preparing for an orderly close 5. Closing communication with the session partner 6.
Sessions Life Cycle of a Session Opening Communication With the Session Partner The establishment of communication with the session partner is the result of executing an HLS–OPEN verb or an OPEN–SESSION verb. A session open Establishes communication with the Tandem SNA access method (for example, the SNAX/CDF process or the SNAX/XF line handler). Possibly awaits a modem connect. (This is determined by rules given in the PROFILE.
Sessions Life Cycle of a Session Pipelined LU Resources An LU resource can be declared as pipelined by setting the PIPELINE–LU–IND to Y. Such resources can be allocated by more than one requester. When an LU is declared as PIPELINED in the RDT entry, all allocation requests must also declare that they expect pipelined LUs.
Sessions Life Cycle of a Session In the operation of the OPEN–SESSION verb, ACCEPT and ACQUIRE differences come into play: If the PROFILE for the session specifies ACQUIRE open mode, SNAX/HLS immediately attempt s to contact the session partner. If the application program is a PLU, a BIND is sent to the SLU session partner. If the application program is a SLU, an INIT-SELF is sent to the PLU session partner.
Sessions Life Cycle of a Session A send queue is also maintained for each LU. Verbs that result in data transmission are queued on this queue for serial execution. Thus, a SEND–DATA verb is queued behind a currently executing SEND–DATA verb. However, responses that must be sent are not queued; they are sent without queuing. Note that a RECEIVE–DATA verb (on a different queue) does not block the execution of any SEND–DATA verb. For increased performance, a SEND–AND–RECEIVE–DATA verb is supported.
Sessions Life Cycle of a Session Partner Data or Other Event—Partner data or other event messages reflect some message or event associated with the systems operator or partner. They are identified by a data type, explained later in this section. If a RECEIVE–DATA verb is used, then in all three cases the top element is removed from the receive data queue and delivered to the application. If, however, the RECEIVE–CONTROL–WAIT verb is used, this is true only in the first two cases.
Sessions Life Cycle of a Session When the RECEIVE–DATA verb is used to receive partner data, the read count on the WRITEREAD operation that carries the RECEIVE–DATA request should be large enough to receive the incoming data. The RECEIVE–DATA verb remains outstanding until data arrives. This can cause physical memory in the application to be tied down for extended periods of time.
Sessions Life Cycle of a Session If the LARGE–MESSAGE–OPTION is enabled using the LMO PROFILE attribute in the RDT, your application program must be engaged in the chaining operations.
Sessions Life Cycle of a Session Contention Contention arises in half–duplex sessions when either partner has the right to send data. If the session is operating in the half–duplex flip/flop and brackets are used, contention arises when one half–session attempts to begin a bracket. The BIND record assigns one half–session as the contention winner, and the other as the contention loser. This enables SNAX/HLS to resolve the contention issue.
Sessions Life Cycle of a Session To use the character maps, specify the name of the charactermap file to SNAX/HLS at startup using the CHARMAPFILE configuration parameter (which defaults to $SYSTEM.SYSTEM.ZCHARMAP). ZCHARMAP is the charactermap file name for NLS–MAPS). A default character map for the SNAX/HLS process can be specified with the CHARMAPNAME configuration parameter, which supports the standard ASCII–to–EBCDIC translation as its default value.
Sessions Life Cycle of a Session Because data elements are delivered in the replies to receive–type verbs without regard to the requester, the following restrictions also apply: If a RECEIVE–CONTROL verb completes and informs the requester that a data element is on the queue, the data may already have been delivered to another requester by the time the requester can issue a RECEIVE–DATA verb in response to the RECEIVE–CONTROL verb notification.
Sessions Life Cycle of a Session (This page left intentionally blank) 3–12 104707 Tandem Computers Incorporated
4 The Standard Verb Interface SNAX/HLS uses a verb concept to allow any program in a Tandem system or network to communicate requests to SNAX/HLS. Verbs are executed and then status is reported with a return code and modifiers. This section discusses return code categories, verb processing, and verb formats. Verb Processing All communication to SNAX/HLS involves a WRITEREAD procedure. The WRITE portion of the I/O process delivers the request and optional data to the SNAX/HLS process.
The Standard Verb Interface Wait Completion Mode In the wait completion mode, SNAX/HLS returns control only when the requested operation is complete. Note that this can involve a long delay, especially for those operations that depend upon actions from the session partner. The wait mode is available on the HLS-OPEN, HLS-CLOSE, HLS-DEALLOCATE, HLS-RESPOND, and HLS-FLOW-CONTROL requests. The flow of a wait operation is shown in Figure 4-2. Figure 4-2.
The Standard Verb Interface Return-Code Categories Figure 4-3.
The Standard Verb Interface Return-Code Categories Figure 4-4.
The Standard Verb Interface Standard Verb Formats Standard Verb All SNAX/HLS verb requests and responses share a common format, described below. Formats Request Format All SNAX/HLS verbs begin with a standard request header as follows: 77 VERB-name-of-request pic 9(4) comp value number. 01 name-of-request-REQUEST. 02 VERB-CODE 02 SESSION-ID pic 9(4) comp. pic 9(4) comp. The verbs whose names begin with the letters HLS- have two additional standard fields: 02 COMPLETION-MODE 02 REQUEST-FORMAT pic X.
The Standard Verb Interface Standard Verb Formats COMPLETION-MODE specifies how you want to be notified of the completion of the request. Not all options are available on any particular verb. I Immediate Response. In this form, the SNAX/HLS server tries to perform the request without any delay. In particular, SNAX/HLS does not send any SNA commands to your partner. If the request succeeds, the reply to the request indicates a successful response.
The Standard Verb Interface Standard Verb Formats RETURN-CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC-OK indicates success. The possible error responses are explained below. A full discussion of the error codes is in Appendix A of the SNAX/HLS Diagnosis and Support Manual..
The Standard Verb Interface Standard Verb Formats (This 4–8 page left intentionally blank) 104707 Tandem Computers Incorporated
5 SNAX/HLS Verbs This section describes all SNAX/HLS verbs except HLS–CALL–USER, which is described in Section 7, “Customization.
SNAX/HLS Verbs CLOSE-SESSION Verb CLOSE-SESSION Verb This verb is used to forcibly terminate a session by closing the LU associated with the session ID. For a primary LU (PLU) session, the cleanup actions taken by the Tandem access method (SNAX/XF or SNAX/CDF) include the transmission of an UNBIND. HLS does a CLOSE (LU) and returns control back to the user process. SNAX/XF thenasynchronously processes the UNBIND request. For a secondary LU (SLU) session, cleanup includes a TERM–SELF (forced).
SNAX/HLS Verbs CLOSE-SESSION Verb Reply Details VERB–CODE identifies the reply by an integer constant (of value 3), named as follows: VERB–CLOSE–SESSION (in SCOBOL) VERB^CLOSE^SESSION (in TAL) SESSION–ID contains one of the following values: 0, which means that the CLOSE–SESSION has succeeded, a nonzero value, or the session ID, which means that the CLOSE–SESSION has failed. RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested.
SNAX/HLS Verbs CONVERT-ERROR-CODE Verb CONVERT-ERROR This verb is used to convert sense data into a format that is usable by SCOBOLX or -CODE Verb COBOL, and to convert SNAX/HLS return codes into printable explanations. Request Format 77 VERB–CONVERT–ERROR–CODE pic 9(4) comp value 9. 01 CONVERT–ERROR–CODE–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 RETURN–CODE 02 SYSTEM–ERROR–CODE 02 USER–ERROR–CODE pic pic pic pic pic 9(4) comp. 9(4) comp. 9(4) comp. S9(4) comp. S9(4) comp.
SNAX/HLS Verbs CONVERT-ERROR-CODE Verb SYSTEM–ERROR–CODE is the field in which you place the first 2 bytes of data to be converted to display format . USER–ERROR–CODE contains the second two bytes of SNA sense data if the SYSTEM-ERROR-CODE contains the first two bytes of SNA sense data. Reply Details VERB–CODE identifies the reply by an integer constant (of value 9), named as follows: VERB–CONVERT–ERROR–CODE (in SCOBOL) VERB^CONVERT^ERROR^CODE (in TAL) SESSION–ID identifies the session.
SNAX/HLS Verbs CONVERT-ERROR-CODE Verb USER–ERROR–DISPLAY is the hexadecimal conversion of the value in USER–ERROR–CODE of the request. RETURN–CODE–MESSAGE is the textual translation of the value in RETURN–CODE of the request. SYSTEM–ERROR–MESSAGE is the textual translation of the value in SYSTEM–ERROR–CODE of the request. Hexadecimal values are represented using the digits 0–9, A–F. The textual translation of SYSTEM–ERROR–CODE and RETURN–CODE contains installation–specified text.
SNAX/HLS Verbs GET-ATTRIBUTES Verb GET-ATTRIBUTES Verb The GET–ATTRIBUTES verb returns information about the current values of PROFILE attributes and BIND attributes for the requested SESSION–ID. The purpose of this verb is to allow users of SNAX/HLS to inquire and dynamically set (by means of SET–ATTRIBUTES verb) certain PROFILE attributes. Two types of request are defined: Request type 1 allows a user to inquire about the value of PROFILE attributes.
SNAX/HLS Verbs GET-ATTRIBUTES Verb Request Format 77 VERB–GET–ATTRIBUTES pic 9(4) comp value 11. 01 GET–ATTRIBUTES–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 REQUEST–TYPE pic 9(4) comp. pic 9(4) comp. pic 9(4) comp. Reply Format (verb code = 11) 01 GET–ATTRIBUTES–REPLY. 02 VERB–CODE 02 SESSION–ID 02 RETURN–CODE 02 SYSTEM–ERROR–CODE 02 USER–ERROR–CODE 02 RETRY–ACTION–CODE 02 REQUEST–TYPE 02 USER–DATA–LENGTH 02 USER–DATA–S pic pic pic pic pic pic pic pic pic 9(4) comp. 9(4) comp. 9(4) comp. S9(4) comp.
SNAX/HLS Verbs GET-ATTRIBUTES Verb Request Details VERB–CODE identifies the request by an integer constant (of value 11), named as follows: VERB–GET–ATTRIBUTES (in SCOBOL) VERB^GET^ATTRIBUTES (in TAL) SESSION–ID identifies this session. SNAX/HLS generates a session ID in response to an OPEN–SESSION and HLS–ALLOCATE verb. REQUEST–TYPE indicates the type of attributes requested.
SNAX/HLS Verbs GET-ATTRIBUTES Verb USER–ERROR–CODE is undefined and should not be analyzed. RETRY–ACTION–CODE is a summary indicator that indicates whether an unsuccessful request should be retried. The value returned here can be installation–defined. REQUEST–TYPE is the same value as the request. USER–DATA–LENGTH is the length (in bytes) of the returned USER–DATA–S.
SNAX/HLS Verbs GET-ATTRIBUTES Verb FMPROFILE contains the binary value defining the FM PROFILE attribute, extracted from byte 3 of the BIND message. You should see one of the values 2, 3, 4 7, or 18. A value of 0 can occur only if a session is not started. PRIPROT contains the 8 bits defining the primary protocol, as extracted from byte 4 of the BIND message. SECPROT contains the 8 bits defining the secondary protocol, as extracted from byte 5 of the BIND message.
SNAX/HLS Verbs HLS-ALLOCATE Verb HLS-ALLOCATE Verb The HLS–ALLOCATE verb identifies and assigns a session for eventual use by the application. The functions implied in this operation are automatically performed when you issue an OPEN–SESSION verb. Once having allocated a session, your process can now receive session–related information such as operator messages (QMSG), open notifications, and so on.
SNAX/HLS Verbs HLS-ALLOCATE Verb Request Format 77 VERB–HLS–ALLOCATE pic 9(4) comp value 14. 01 HLS–ALLOCATE–REQUEST. 02 VERB–CODE pic 9(4) comp. 02 SESSION–ID pic 9(4) comp. 02 COMPLETION–MODE pic X. (I) 02 REQUEST–FORMAT pic X value space. 02 LU–NAME pic X(24). 02 PROFILE–NAME pic X(8). 02 PIPELINE–LU–IND pic X.(Y or N) 02 FUTURE pic X(7). Reply Format (verb–code = 14) 01 HLS–ALLOCATE–REPLY.
SNAX/HLS Verbs HLS-ALLOCATE Verb COMPLETION–MODE specifies the way the SNAX/HLS server responds to your request. One of the supported alternatives must be supplied. These alternatives are: I Immediate response. For a complete discussion of these completion modes, refer to Section 4, “The Standard Verb Interface.” REQUEST–FORMAT is reserved for future expansion of the verb. It must contain a blank. LU–NAME identifies the SNALU LU being allocated.
SNAX/HLS Verbs HLS-ALLOCATE Verb PROFILE–NAME identifies the name of a PROFILE. If the session is not yet allocated, this field must be nonblank and contain a name of one of the entries in the currently defined RDT to satisfy this PROFILE. If the session is already allocated but this field is blank, or the field contains the same name as the one currently associated with the session, the request is satisfied with no change.
SNAX/HLS Verbs HLS-ALLOCATE Verb RETURN–CODE is a binary field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below. See Appendix A of the SNAX/HLS Diagnosis and Support Manual for more information on error codes. SYSTEM–ERROR–CODE is a modifier to RETURN–CODE.
SNAX/HLS Verbs HLS CLOSE Verb HLS-CLOSE Verb The HLS–CLOSE verb breaks the connection between the partners of the session. If more than one connection has opened the session, only the last HLS–CLOSE request actually performs the close. The requester must be an opener of the session. This verb need not be used unless your application needs to retain the LU in an allocated state (see HLS–DEALLOCATE verb, below).
SNAX/HLS Verbs HLS CLOSE Verb Request Format 77 VERB–HLS–CLOSE pic 9(4) comp value 17. 01 HLS–CLOSE–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 COMPLETION–MODE 02 REQUEST–FORMAT 02 CLOSE–REASON 02 SENSE–TEXT 03 SENSE–DATA Reply Format (verb–code = 17) 01 HLS–CLOSE–REPLY.
SNAX/HLS Verbs HLS CLOSE Verb COMPLETION–MODE specifies the way the SNAX/HLS server responds to your request. One of the supported alternatives must be supplied. These alternatives are: Q Queued response. W Wait response. The SNAX/HLS server replies to you only after a Q request is complete. For a complete discussion of these completion modes, refer to Section 4, “The Standard Verb Interface.” REQUEST–FORMAT is reserved for future expansion of the verb. This field must contain a blank.
SNAX/HLS Verbs HLS CLOSE Verb RETURN–CODE is a binary field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below. See the SNAX/HLS Diagnosis and Support Manual for more information on error codes. SYSTEM–ERROR–CODE is a modifier to RETURN–CODE.
SNAX/HLS Verbs HLS CLOSE Verb Figure 5–2 shows a session example for the case of a PLU issuing an HLS–CLOSE verb. Figure 5–2. Example of PLU HLS–CLOSE REQUESTER (PLU) SNAX/HLS SNALU INTERFACE PARTNER (SLU) HLS-CLOSE request CALL CLOSE (lu) HLS-CLOSE reply UNBIND (+RSP) Figure 5–3 shows a session example for the case of an SLU issuing an HLS–CLOSE verb. Figure 5–3.
SNAX/HLS Verbs HLS DEALLOCATE Verb HLS-DEALLOCATE Verb The HLS–DEALLOCATE verb causes the LU name to be deallocated. You must be an allocator of this LU name. This is an enhanced verb, and is permitted only if the session was allocated by the HLS–ALLOCATE verb. If more than one requester has allocated the session, it is the last deallocator that actually releases the resources held by SNAX/HLS. If this verb is issued on a session that is currently open, the session is closed.
SNAX/HLS Verbs HLS DEALLOCATE Verb COMPLETION–MODE specifies the way the SNAX/HLS server responds to your request. One of the supported alternatives must be supplied. These alternatives are: Q Queued response. W Wait response. The SNAX/HLS server replies to you only after a Q request is complete. For a complete discussion of these completion modes, refer to Section 4, “The Standard Verb Interface.” REQUEST–FORMAT is reserved for future expansion of the verb. This field must contain a blank.
SNAX/HLS Verbs HLS DEALLOCATE Verb RETRY–ACTION–CODE is a summary indicator that indicates whether an unsuccessful request should be retried. The value returned here can be installation–defined.
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb HLS-FLOW-CONTROL Verb This specialized SNA verb, which presumes a fairly detailed knowledge of SNA, allows you to send one of four different flow control messages to your partner. Three messages deal with the initiation of messages, and one deals with the initiation of transactions. Table 5-1 shows the SNA messages that correspond to this verb. Table 5-1.
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb When you are willing to have your partner start a bracket, you can send the HLS–FLOW–CONTROL (RT) message. Stop Sending Messages (SM)—This variant directs SNAX/HLS to send an SNA QEC request to the session partner. QEC is a message defined by SNA that is used to request that no new messages (chains) be sent.
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb Request Format 77 VERB–HLS–FLOW–CONTROL pic 9(4) comp value 19. 01 HLS–FLOW–CONTROL–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 COMPLETION–MODE 02 REQUEST–FORMAT 02 OPERATION 02 OBJECT pic pic pic pic pic pic 9(4) comp. 9(4) comp. X. (Q or W) X value space. X. (S, Q or R) X. (T or M) Reply Format (verb–code = 19) 01 HLS–FLOW–CONTROL–REPLY.
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb COMPLETION–MODE specifies the way the SNAX/HLS server responds to your request. One of the supported alternatives must be supplied. These alternatives are: Q Queued response. W Wait response. The SNAX/HLS server replies to you only after a Q request is complete. For a complete discussion of these completion modes, refer to Section 4, “The Standard Verb Interface.” REQUEST–FORMAT is reserved for future expansion of the verb. This field must contain a blank.
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below. See Appendix A of the SNAX/HLS Diagnosis and Support Manual for more information on error codes.
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb Figure 5–4 shows a session example using the HLS–FLOW–CONTROL (SM) verb. Figure 5–4 . Example of HLS–FLOW–CONTROL (SM) USER SNAX/HLS SNALU INTERFACE PARTNER session established data transfer in operation . HLS-FLOW-CONTROL request OPERATION=S OBJECT=M QEC (+RSP) HLS-FLOW-CONTROL reply RETURN-CODE=OK . The partner finishes up message in progress, then confirms the stop request: . RECEIVE-DATA request .
SNAX/HLS Verbs HLS-FLOW-CONTROL Verb Figure 5–5 shows a session example using the HLS–FLOW–CONTROL (RT) verb. Figure 5–5. Example of HLS–FLOW–CONTROL (RT) First Speaker SNAX/HLS SNALU INTERFACE Bidder session established data transfer in operation .
SNAX/HLS Verbs HLS-OPEN Verb HLS-OPEN Verb The HLS–OPEN verb is used to make sure that the resource that was allocated in a previous HLS–ALLOCATE verb is now ready for traffic. This operation performs the SNA operations of INIT–SELF or BIND, and STSN and SDT as required by the session rules. If the session is already open, the request is accepted and completed immediately. This is the only way in which this request with COMPLETION–MODE is I can complete with RC–OK. A session can have more than one opener.
SNAX/HLS Verbs HLS-OPEN Verb The APPLICATION–NAME field can be used to establish dynamic passthrough sessions. As an example of such a situation, consider the configuration shown in Figure 5–6. This figure is explained in detail below. Figure 5–6. Example of HLS–OPEN \PARIS Secondary acquire LU Issue HLS-OPEN, using \TEXAS.$SNA1.TSO as application-name Send INIT-SELF specifying \TEXAS.$SNA1.
SNAX/HLS Verbs HLS-OPEN Verb 5–34 1. Your application program resides on node \PARIS and issues an HLS–OPEN specifying an APPLICATION–NAME of \TEXAS.$SNA1.TSO. However, the SNA line on which your application resides is a secondary line, with the primary driven from another Tandem node, \NEWYORK.$SNA8. 2. An INIT–SELF, bearing the application name of \TEXAS.$SNA1.TSO, flows out of your node (\PARIS) and is received by the primary on \NEWYORK.$SNA8. 3.
SNAX/HLS Verbs HLS-OPEN Verb Request Format 77 VERB–HLS–OPEN pic 9(4) comp value 15. 01 HLS–OPEN–REQUEST. 02 VERB–CODE pic 9(4) comp. 02 SESSION–ID pic 9(4) comp. 02 COMPLETION–MODE pic X. (I or Q or W) 02 REQUEST–FORMAT pic X value space. 02 APPLICATION–NAME pic X(32). 02 VERIFY–SEQUENCE–NUMBERS–IND pic X. 02 FUTURE pic X(7). 02 RECOVERY–TAGS. 03 SEND–SEQUENCE–NUMBER pic S9(4) comp. 03 RCV–SEQUENCE–NUMBER pic S9(4) comp. 02 USER–DATA–LENGTH pic 9(4) comp.
SNAX/HLS Verbs HLS-OPEN Verb SESSION–ID requires the session ID that the SNAX/HLS server returned in response to the HLS–ALLOCATE verb. COMPLETION–MODE specifies the way the SNAX/HLS server responds to your request. One of the supported alternatives must be supplied. These alternatives are: I Immediate response. W Wait response. Q Queued response. For a complete discussion on completion modes, refer to Section 4, “The Standard Verb Interface.” REQUEST–FORMAT is reserved for future expansion of the verb.
SNAX/HLS Verbs HLS-OPEN Verb You wish to invoke dynamic passthrough, and the application name encodes the identity of the line and the name of the host application. VERIFY–SEQUENCE–NUMBERS–IND indicates whether SNAX/HLS performs sequence number verification. This is valid only if TS PROFILE 4 is in use on the SNA session. (The TS PROFILE level is specified by a field in the SNA BIND request.) If VERIFY–SEQUENCE–NUMBERS–IND is N, no sequence number verification occurs.
SNAX/HLS Verbs HLS-OPEN Verb USER–DATA–S is used to specify user data that is appended to the BIND or INIT–SELF messages generated at session open. On secondary accept LUs, this field is ignored. The total length of the user data must not cause the BIND or INIT–SELF image to exceed 256 bytes in length. Since these messages can vary in length, a precise limit cannot be specified.
SNAX/HLS Verbs HLS-OPEN Verb SYSTEM–ERROR–CODE is a modifier to RETURN–CODE: If RETURN–CODE specifies RC–SYNTAX–ERROR, this identifies the field in error by counting each field following the REQUEST–FORMAT field. For example, a value of 1 indicates that the first field following the REQUEST–FORMAT field is in error. If RETURN–CODE contains either RC–SEND–CHECK, RC–SESSION–FAILURE, or RC–REQUEST–REJECT, then this field contains the first 2 bytes of the SNA sense data.
SNAX/HLS Verbs HLS-OPEN Verb Figure 5–7 shows a session example using the HLS–OPEN verb for the primary acquire case. Figure 5–7. Example of Primary Acquire REQUESTER (PLU) SNAX/HLS SNALU INTERFACE PARTNER (SLU) HLS-OPEN request BIND (+RSP) STSN (+RSP) SDT (+RSP) HLS-OPEN reply RETURN-CODE=OK The STSN and SDT messages in all the HLS–OPEN diagrams flow only if required by the session rules.
SNAX/HLS Verbs HLS-OPEN Verb Figure 5–8 shows a session example using the HLS–OPEN verb for the primary accept case. Figure 5–8. Example of: Primary Accept REQUESTER (PLU) SNAX/HLS SNALU INTERFACE PARTNER (SLU) HLS-OPEN request . (Wait for CINIT) . LOGON or INIT-SELF (+RSP) CINIT (+RSP) BIND (+RSP) STSN (+RSP) SDT (+RSP) HLS-OPEN reply RETURN-CODE=OK Note that the initial SNA transmission that starts the session originates in the SLU.
SNAX/HLS Verbs HLS-OPEN Verb Figure 5–9 shows a session example using the HLS–OPEN verb for the secondary acquire case. Figure 5–9. Example of Secondary Acquire REQUESTER (SLU) SNAX/HLS SNALU INTERFACE PARTNER (PLU) HLS-OPEN request INIT-SELF (+RSP) BIND (+RSP) STSN (+RSP) SDT (+RSP) HLS-OPEN reply RETURN-CODE=OK Figure 5–10 shows a session example using the HLS–OPEN verb for the secondary accept case. Figure 5–10.
SNAX/HLS Verbs HLS RESPOND Verb HLS-RESPOND Verb The HLS–RESPOND verb directs SNAX/HLS to issue a response to previously received partner data. The verb is legal only if the PROFILE indicates that USER–RESPONSES is YES. If the verb is issued when USER–RESPONSES are not enabled, it is treated as an illegal verb, producing the return code of RC–INVALID–VERB.
SNAX/HLS Verbs HLS RESPOND Verb Request Details VERB–CODE identifies the request by an integer constant (of value 18), named as follows: VERB–HLS–RESPOND (in SCOBOL) VERB^HLS^RESPOND (in TAL) SESSION–ID identifies this session. SNAX/HLS generates a session ID in response to an OPEN–SESSION or an HLS–ALLOCATE verb. COMPLETION–MODE specifies the way the SNAX/HLS server responds to your request. and must be supplied: W Wait response. The SNAX/HLS server replies to you only after a Q request is complete.
SNAX/HLS Verbs HLS RESPOND Verb MESSAGE–TAG contains the message tag that identifies which original request is being answered. The original reply with which your application received the data bore two tag values in the RECOVERY–TAGS field. Although any value contained between the BOM and EOM values identifies the request, SNAX/HLS converts your value to the EOM value, which is the conventional way to identify messages. However, if the response is negative, no such conversion takes place.
SNAX/HLS Verbs HLS RESPOND Verb USER–ERROR–CODE contains the second two bytes of SNA sense data if the SYSTEM-ERROR-CODE contains the first two bytes of SNA sense data. RETRY–ACTION–CODE is a summary indicator that indicates whether an unsuccessful request should be retried. The value returned here can be installation–defined.
SNAX/HLS Verbs OPEN-SESSION Verb OPEN-SESSION Verb This verb is used to establish a session between two session partners (that is, LUs). The detailed operation of the verb depends on both the PROFILE attributes (for example, OPEN–MODE) and the BIND attributes (for example, TS PROFILE). The SNAX/HLS system programmer defines the appropriate values in the RDT for PROFILE, BIND, or INIT attributes.
SNAX/HLS Verbs OPEN-SESSION Verb Request Format 77 VERB–OPEN–SESSION pic 9(4) comp value 1. 01 OPEN–SESSION–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 LU–NAME 02 PROFILE–NAME 02 APPLICATION–NAME 02 PIPELINE–LU–IND 02 VERIFY–SEQUENCE–NUMBERS–IND 02 FUTURE 02 RECOVERY–TAGS. 03 SEND–SEQUENCE–NUMBER 03 RCV–SEQUENCE–NUMBER Reply Format (verb–code = 1) 01 OPEN–SESSION–REPLY. 02 VERB–CODE 02 SESSION–ID 02 RETURN–CODE 02 SYSTEM–ERROR–CODE 02 USER–ERROR–CODE 02 RETRY–ACTION–CODE 02 RECOVERY–TAGS.
SNAX/HLS Verbs OPEN-SESSION Verb Request Details VERB–CODE identifies the request by an integer constant (of value 1), named as follows: VERB–OPEN–SESSION (in SCOBOL) VERB^OPEN^SESSION (in TAL) SESSION–ID is unused. LU–NAME identifies the SNALU LU being allocated. At present, only the name of a SNAX/XF LU or the OPENNAME of the SNAX/CDF APPL object can be specified. They are represented in standard internal file format. PROFILE–NAME is the name of a PROFILE record in the RDT (Resource Definition Table).
SNAX/HLS Verbs OPEN-SESSION Verb VERIFY–SEQUENCE–NUMBERS–IND dictates whether SNAX/HLS performs sequence number verification. This is valid only if TS PROFILE 4 is in use on the SNA session. (The TS PROFILE level is specified by a field in the SNA BIND request.) If VERIFY–SEQUENCE–NUMBERS–IND is N, no sequence number verification occurs.
SNAX/HLS Verbs OPEN-SESSION Verb SESSION–ID contains one of the following: Zero. There is no session ID because the SNAX/HLS server could not begin the session. See the error response. A nonzero value, the session ID of the new session. RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below.
SNAX/HLS Verbs OPEN-SESSION Verb RECOVERY–TAGS contains the sequence numbers actually in effect by the session partner. SEND–SEQUENCE–NUMBER contains the session partner’s value for the current user’s send tag of this session (that is, the message tag of the next message to be received by the session partner). The intent of this field is to give the user feedback on situations when sequence verification is negative.
SNAX/HLS Verbs PREPARE-TO-CLOSE Verb PREPARE-TO-CLOSE Verb The PREPARE–TO–CLOSE verb is used to terminate a session in an orderly fashion. Use of this verb is encouraged to ensure that both session partners are aware that a session is about to be terminated, thus allowing each to do clean–up processing. The PREPARE–TO–CLOSE verb, if issued by the primary partner (PLU), indicates a readiness to terminate the session. The SLU receives the request but can still send and receive data on the session.
SNAX/HLS Verbs PREPARE-TO-CLOSE Verb Request Format 77 VERB–PREPARE–TO–CLOSE pic 9(4) comp value 2. 01 PREPARE–TO–CLOSE–REQUEST. 02 VERB–CODE 02 SESSION–ID pic 9(4) comp. pic 9(4) comp. Reply Format (verb–code = 2) 01 PREPARE–TO–CLOSE–REPLY. 02 VERB–CODE 02 SESSION–ID 02 RETURN–CODE 02 SYSTEM–ERROR–CODE 02 USER–ERROR–CODE 02 RETRY–ACTION–CODE pic pic pic pic pic pic 9(4) comp. 9(4) comp. 9(4) comp. S9(4) comp. S9(4) comp. 9(4) comp.
SNAX/HLS Verbs PREPARE-TO-CLOSE Verb Reply Details VERB–CODE identifies the reply by an integer constant (of value 2), named as follows: VERB–PREPARE–TO–CLOSE (in SCOBOL) VERB^PREPARE^TO^CLOSE (in TAL) SESSION–ID identifies the session RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below.
SNAX/HLS Verbs PREPARE-TO-CLOSE Verb Figure 5–11 shows a session example of a PLU issuing the PREPARE–TO–CLOSE verb. This example shows the SNAX/HLS server acting as both the PLU and the SLU. Figure 5–11. Example of PLU PREPARE–TO–CLOSE PLU (SNA TRAFFIC) SLU RECEIVE-DATA request PREPARE-TO-CLOSE request SHUTD RECEIVE-DATA reply DATA-TYPE= DT-PREPARED-TO-CLOSE (+RSP) PREPARE-TO-CLOSE reply . When the SLU is ready to close: .
SNAX/HLS Verbs PREPARE-TO-CLOSE Verb Figure 5–12 shows a session example of an SLU issuing a PREPARE–TO–CLOSE verb. In this example the SNAX/HLS server is acting as both PLU and SLU. Figure 5–12.
SNAX/HLS Verbs RECEIVE-CONTROL Verb RECEIVE-CONTROL RECEIVE–CONTROL is mainly intended for a nowait check of the user receive queue. Verb It permits your application to check for the presence of data on the receive queue. Responses to previously sent data and queued completions are be removed from your receive queue. That is, when SNAX/HLS performs a RECEIVE–CONTROL verb, the top element of the receive queue for the session ID is inspected.
SNAX/HLS Verbs RECEIVE-CONTROL Verb Request Format 77 VERB–RECEIVE–CONTROL pic 9(4) comp value 4. 01 RECEIVE–CONTROL–REQUEST. 02 VERB–CODE 02 SESSION–ID Reply Format (verb–code = 4) 01 RECEIVE–CONTROL–REPLY. 02 VERB–CODE 02 SESSION–ID 02 RETURN–CODE 02 SYSTEM–ERROR–CODE 02 USER–ERROR–CODE 02 RETRY–ACTION–CODE 02 RECOVERY–TAGS.
SNAX/HLS Verbs RECEIVE-CONTROL Verb Reply Details VERB–CODE identifies the reply by an integer constant (of value 4), named as follows: VERB–RECEIVE–CONTROL (in SCOBOL) VERB^RECEIVE^CONTROL (in TAL) SESSION–ID identifies the session. RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below.
SNAX/HLS Verbs RECEIVE-CONTROL Verb RECOVERY–TAGS are returned to allow the requester to correlate requests, responses, and/or replies. BOM is the SNA sequence number of the first element of the data message, and EOM is the SNA sequence number of the last element of the data message.
SNAX/HLS Verbs RECEIVE-CONTROL Verb MESSAGE–COMPLETE–IND A value of Y indicates that the current message in the user buffer is a complete user message (although the message could be truncated if RC–DATA–TRUNCATED is returned). A value of N can be returned only when using the LMO feature and indicates that subsequent RECEIVE–DATA verbs retrieves more elements of the session partner’s message. This field is meaningful only when your partner’s data is being returned.
SNAX/HLS Verbs RECEIVE-CONTROL Verb Table 5-2. Definite–Response Indicators Value Delivered to Application Program DR and ER Bits on SNA Message None DR1 DR2 DR1 & DR2 DR1 & ERI DR2 & ERI DR1 & DR2 & ERI ENCODE–ERI = N ENCODE–ERI = Y 0 1 2 3 1 2 3 0 1 2 3 5 6 7 DATA–TYPE–RECEIVED is a computational value indicating the kind of data that was received. The codes are as follows: negative An FMH header is present in the data.
SNAX/HLS Verbs RECEIVE-CONTROL Verb 7 (Name is DT–MESSAGE–CANCELLED.) The session partner has canceled the current message. This value can be delivered only under the LMO is Y condition. The current message is to be disregarded. 8 (Name is DT–BIND–CINIT–DATA.) The session has just been established.
SNAX/HLS Verbs RECEIVE-CONTROL Verb It is highly unlikely that your application needs to know the precise reason that the session was closed, but, if it does, the data–reply area contains the actual SNA message unit that caused the closure. For example, if the closure occurred because your partner issued a normal UNBIND command (this can happen only if you are secondary), you receive a 2–byte message containing the value %H3201. 10 (Name is DT–FLOW–CONTROL.
SNAX/HLS Verbs RECEIVE-CONTROL Verb 11 (Name is DT–BID–REJECTED.) This message occurs only if your PROFILE specified USER for the BID–REJECTION attribute. It indicates that a negative response of 0814 was sent to your partner. That response specifies to your partner that its attempt to initiate a bracket was rejected and that you send an RTR message when the partner can try again. Your application should, when convenient, send the RTR using the HLS–FLOW–CONTROL(RT) verb.
SNAX/HLS Verbs RECEIVE-CONTROL Verb Figure 5–13 shows an example of the RECEIVE–CONTROL verb with partner data waiting on the receive queue. Figure 5–13. Example of RECEIVE–CONTROL VERB SNAX/HLS SNA FLOW #1:BC,RQE(data) #2:RQE(data) #3:EC,RQD(data) RECEIVE-CONTROL request RECEIVE-CONTROL reply RETURN-CODE=OK DATA-TYPE-RECEIVED= DT-PARTNER-DATA NOTE: Data is not removed from the queue.
SNAX/HLS Verbs RECEIVE-CONTROL Verb Figure 5–14 shows an example of the RECEIVE–CONTROL verb with a negative response waiting on the queue. The session is operating in exception response mode. Figure 5–14. Example of RECEIVE–CONTROL VERB SNAX/HLS SNA FLOW SEND-DATA request #1:BC,RQE(data) #2:EC,RQE(data) SEND-DATA reply RETURN-CODE=OK (-RSP,#2) RECEIVE-CONTROL request SEND-DATA reply RETURN-CODE=REQUEST-REJECT NOTE: 5–68 The negative response is removed from the queue.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb RECEIVE- The RECEIVE–CONTROL–WAIT verb provides a waited form of the CONTROL-WAIT Verb RECEIVE–CONTROL verb. Note that the request and reply structures given below are exactly those for the RECEIVE–CONTROL verb. If the receive queue for the session is not empty when the verb is issued, the verb is replied to immediately. If the receive queue for the session is empty, the verb is queued for later processing.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb There are a number of restrictions on the use of the RECEIVE–CONTROL–WAIT verb: Only one RECEIVE–CONTROL–WAIT verb may be outstanding on a SNAX/HLS session. A RECEIVE–CONTROL–WAIT verb issued while one such verb is already outstanding on the session, is rejected with a return code of RC^RCWT^ALREADY^QUEUED. A RECEIVE–DATA verb issued while a RECEIVE–CONTROL–WAIT verb is already outstanding on the session, is rejected with a return code of RC^RCWT^ALREADY^QUEUED.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb Request Format 77 VERB–RECEIVE–CONTROL–WAIT pic 9(4) comp value 20. 01 RECEIVE–CONTROL–WAIT–REQUEST. 02 VERB–CODE 02 SESSION–ID pic pic 9(4) comp. 9(4) comp. Reply Format ( verb–code = 20 ) 01 RECEIVE–CONTROL–WAIT–REPLY.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb Reply Details VERB–CODE identifies the reply by an integer constant (of value 4), named as follows: VERB–RECEIVE–CONTROL–WAIT (in SCOBOL) VERB^RECEIVE^CONTROL^WAIT (in TAL) SESSION–ID identifies the session. RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC–OK indicates success. The possible error responses are explained below.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb RECOVERY–TAGS are returned to allow the requester to correlate requests, responses, and/or replies. BOM is the SNA sequence number of the first element of the data message, and EOM is the SNA sequence number of the last element of the data message.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb DEFINITE–RESPONSE–IND is a single–character numeric field that indicates the kind of response the partner is expecting for this request. For those who know SNA, it reflects the setting of the DR1I and DR2I indicators at the end of the incoming request (that is, end of chain). If the PROFILE attribute, ENCODE–ERI, is set to TRUE, the setting of the ERI indicator is also indicated.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb 3 (Name is DT–PREPARED–TO–CLOSE.) The session partner is prepared for session termination. 4 (Name is DT–LU–STATUS.) LUSTAT has been received from the session partner. This might indicate SNA information or session– partner unique information. 5 (Name is DT–SIGNAL.) The session partner has sent an SNA SIG message.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb In some cases (most noticeably, in TSO sessions), you might receive two copies of the message because your partner issued a temporary UNBIND command and then rebound the session. 9 (Name is DT–SESSION–CLOSED.) The session has just been closed by partner. The message contains information indicating why the session was closed. This message can be delivered only if you created the session with the HLS–ALLOCATE and HLS–OPEN verbs.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb RM (SNA RELQ message.) This message was sent by your partner to indicate that message traffic can resume. It most frequently is used after traffic was stopped by previously issued QEC and QC messages, or after the sessions have exchanged PREPARE–TO–CLOSE messages. (Name is DT–BID–REJECTED.) This message occurs only if your PROFILE specified USER for the BID–REJECTION attribute. It indicates that a negative response of 0814 was sent to your partner.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb Figure 5-16 shows the RECEIVE–CONTROL–WAIT verb in use on a SNAX/HLS session. In this session, a negative response from the session partner is queued in response to a previously sent message. Figure 5-16.
SNAX/HLS Verbs RECEIVE-CONTROL-WAIT Verb Figure 5–17 shows the operation of the RECEIVE–CONTROL–WAIT verb in use on a SNAX/HLS session, not using the large message option (LMO), and on which a RECEIVE–DATA verb is already outstanding. Figure 5-17.
SNAX/HLS Verbs RECEIVE DATA Verb REVEIVE-DATA Verb The RECEIVE–DATA verb is used to transfer the top element of the receive queue to the user. If the receive queue is currently empty, the completion of this verb waits until some data arrives, the session is terminated, or a SCOBOLX SEND MESSAGE operation is interrupted.
SNAX/HLS Verbs RECEIVE DATA Verb If VERB–CODE in REQUEST–HEADER has the value VERB–RECEIVE–DATA, SNAX/HLS delivers the message in a format that expects the user–data field to be a variable–length array (this is an OCCURS DEPENDING ON clause in COBOL/SCOBOLX). In this way, the user does not have to furnish the data length expected in the verb–request code. The interpretation of TRANSACTION–IN–PROGRESS–IND requires some care.
SNAX/HLS Verbs RECEIVE DATA Verb Request Format 77 VERB–RECEIVE–DATA pic 9(4) comp value 5. 01 RECEIVE–DATA–REQUEST. 02 VERB–CODE 02 SESSION–ID pic 9(4) comp. pic 9(4) comp. When data is from the session partner, interrupt, or SSCP. Reply Format (verb–code = 5) 01 RECEIVE–DATA–REPLY. 02 VERB–CODE pic 9(4) comp. 02 SESSION–ID pic 9(4) comp. 02 RETURN–CODE pic 9(4) comp. 02 SYSTEM–ERROR–CODE pic S9(4) comp. 02 USER–ERROR–CODE pic S9(4) comp. 02 RETRY–ACTION–CODE pic 9(4) comp. 02 RECOVERY–TAGS.
SNAX/HLS Verbs RECEIVE DATA Verb Request Details VERB–CODE identifies the request by an integer constant (of value 7), named as follows: VERB–RECEIVE–DATA (in SCOBOL) VERB^RECEIVE^DATA (in TAL) SESSION–ID identifies this session. SNAX/HLS generates a session ID in response to an OPEN–SESSION or an HLS–ALLOCATE verb. Reply Details VERB–CODE identifies the reply by an integer constant (of value 7), named as follows: VERB–RECEIVE–DATA (in SCOBOL) VERB^RECEIVE^DATA (in TAL) SESSION–ID identifies the session.
SNAX/HLS Verbs RECEIVE DATA Verb If RETURN–CODE contains any value other than those listed above, this field is undefined and should not be analyzed. USER–ERROR–CODE contains the second two bytes of SNA sense data if the SYSTEM-ERROR-CODE contains the first two bytes of SNA sense data. RETRY–ACTION–CODE is a summary indicator that indicates whether an unsuccessful request should be retried. The value returned here can be installation–defined.
SNAX/HLS Verbs RECEIVE DATA Verb TRANSACTION–IN–PROGRESS–IND. A value of Y indicates that you are in a transaction. If the current session PROFILE does not support transactions (SNA brackets), the value is N. It reflects the conditions following the receipt of the message in question. If you have just received a partner–data message, you can use this indication to detect whether the end–bracket flag was set on the message you just received.
SNAX/HLS Verbs RECEIVE DATA Verb Table 5-3 reflects the value delivered to this field: Table 5-3. Definite–Response Indicators Value Delivered to Application Program DR and ER Bits on SNA Message None DR1 DR2 DR1 & DR2 DR1 & ERI DR2 & ERI DR1 & DR2 & ERI ENCODE–ERI = N ENCODE–ERI = Y 0 1 2 3 1 2 3 0 1 2 3 5 6 7 DATA–TYPE–RECEIVED is a computational value indicating the kind of data that was received. The codes are as follows: 5–86 negative An FMH header is present in the data.
SNAX/HLS Verbs RECEIVE DATA Verb 6 (Name is DT–REQUEST–CLOSE.) The session partner demands that you issue a CLOSE–SESSION verb. 7 (Name is DT–MESSAGE–CANCELLED.) The session partner has canceled the current message. This value can only be delivered under the LMO is Y condition. The current message is to be disregarded. 8 (Name is DT–BIND–CINIT–DATA.) The session has just been established.
SNAX/HLS Verbs RECEIVE DATA Verb created the session with the HLS–ALLOCATE and HLS–OPEN verbs. It is highly unlikely that your application needs to know the precise reason that the session was closed, but , if it does, the data reply area contains the actual SNA message unit that caused the closure. For example, if the closure occurred because the session partner issued a normal UNBIND command (this can happen only if you are secondary), you receive a 2–byte message containing the value %H3201.
SNAX/HLS Verbs RECEIVE DATA Verb 11 (Name is DT–BID–REJECTED.) This message occurs only if your PROFILE specified USER for the BID–REJECTION attribute. It indicates that a negative response of 0814 was sent to your partner. That response specifies to your partner that its attempt to initiate a bracket was rejected and that you send an RTR message when the partner can try again. Your application should, when convenient, send the RTR using the HLS–FLOW–CONTROL(RT) verb.
SNAX/HLS Verbs RECEIVE DATA Verb Figure 5–18. Example of RECEIVE–DATA VERB SNAX/HLS SNA FLOW #1:BC,RQE(data) #2:RQE(data) #3:EC,RQD(data) RECEIVE-DATA request +RSP(#3) RECEIVE-DATA reply RETURN-CODE=OK DATA-TYPE-RECEIVED= DT-PARTNER-DATA BOM=1 EOM=3 Note that the response to the partner data is not generated until the data is retrieved by the application.
SNAX/HLS Verbs RECEIVE DATA Verb Figure 5–19.
SNAX/HLS Verbs REQUEST SEND STATE Verb REQUEST-SENDSTATE Verb This verb causes the SNA SIG request to be sent to the session partner. The signal code is %H0001, indicating REQUEST–TO–SEND (that is, the sender of SIG wishes to send data). If the session is not in receive state when this verb is issued (for example, FDX PROFILE, or contention state in HDX profiles), SNAX/HLS treats the verb as a null operation, unless the PROFILE attribute FORCE–RTS is set to TRUE.
SNAX/HLS Verbs REQUEST SEND STATE Verb SESSION–ID identifies this session. SNAX/HLS generates a session ID in response to an OPEN–SESSION or an HLS–ALLOCATE verb. Reply Details VERB–CODE identifies the reply by an integer constant (of value 6), named as follows: VERB–REQUEST–SEND–STATE (in SCOBOL) VERB^REQUEST^SEND^STATE (in TAL) SESSION–ID identifies the session. RETURN–CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested.
SNAX/HLS Verbs REQUEST SEND STATE Verb Figure 5–20 shows a session example using the REQUEST–SEND–STATE verb. Figure 5–20.
SNAX/HLS Verbs SEND-AND-RECEIVE-DATA Verb SEND-AND- The SEND–AND–RECEIVE–DATA verb acts like a specialized SEND–DATA followed RECEIVE-DATA Verb immediately by a RECEIVE–DATA verb. If the session is using half–duplex flip–flop protocol, SNAX/HLS automatically sets the PREPARE–TO–RECEIVE–IND to Y. Furthermore, in LMO mode, this request cannot be used if the MESSAGE–COMPLETE–IND is N. If a send–check occurs (that is, something goes wrong with the SEND–DATA portion), then SNAX/HLS formats a reply to SEND–DATA.
SNAX/HLS Verbs SEND-AND-RECEIVE-DATA Verb Request Format 77 VERB–SEND–AND–RECEIVE–DATA pic 9(4) comp value 10. 01 SEND–AND–RECEIVE–DATA–REQUEST. 02 VERB–CODE pic 9(4) comp. 02 SESSION–ID pic 9(4) comp. 02 PREPARE–TO–RECEIVE–IND pic X. (Y or N) 02 END–TRANSACTION–IND pic X. (Y or N) 02 FORMATTED–DATA–IND pic X. (Y or N) 02 NOTIFY–IND pic X. (Y or N) 02 MESSAGE–COMPLETE–IND pic X. (Y or N) 02 RESERVED–FOR–FUTURE–USE pic X. 02 USER–DATA–LENGTH pic 9(4) comp.
SNAX/HLS Verbs SEND-AND-RECEIVE-DATA Verb Reply Format The reply formats are either those described under SEND–DATA, or under RECEIVE– DATA, depending upon whether the send portion failed or succeeded. Figure 5–21 shows the SEND–AND–RECEIVE–DATA verb flow. The session is using definite response and immediate request modes, and the PROFILE in use on the session indicates USER–RESPONSES is NO.
SNAX/HLS Verbs SEND-DATA Verb SEND-DATA Verb This verb requests SNAX/HLS to transmit the contents of the user–data field. The operation of this verb depends on the current setting of the LMO PROFILE attribute. If the current value of LMO is NO, then SNAX/HLS divides the message into an SNA chain of MAXRU bytes each (except the last element of the chain). See the SNAX/HLS Configuration and Control Manual for a discussion of the MAXRU field in the PROFILE.
SNAX/HLS Verbs Response Protocols 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 field in the SEND-DATA and SEND-AND-RECEIVE-DATA verbs. Table 5-4 shows the protocol actually used. Table 5-4.
SNAX/HLS Verbs SEND-DATA-Verb Send-DATA Verb Request Format 77 VERB–SEND–DATA pic 9(4) comp value 7. 01 SEND–DATA–REQUEST. 02 VERB–CODE pic 9(4) comp. 02 SESSION–ID pic 9(4) comp. 02 PREPARE–TO–RECEIVE–IND pic X. (Y or N) 02 END–TRANSACTION–IND pic X. (Y or N) 02 FORMATTED–DATA–IND pic X. (Y or N) 02 NOTIFY–IND pic X. (Y or N) 02 MESSAGE–COMPLETE–IND pic X. (Y or N) 02 RESERVED–FOR–FUTURE–USE pic X. 02 USER–DATA–LENGTH pic 9(4) comp.
SNAX/HLS Verbs SEND-DATA-Verb Request Details VERB–CODE identifies the request by an integer constant (of value 7), named as follows: VERB–SEND–DATA (in SCOBOL) VERB^SEND^DATA (in TAL) SESSION–ID identifies this session. SNAX/HLS generates a session ID in response to an OPEN–SESSION or an HLS–ALLOCATE verb. PREPARE–TO–RECEIVE–IND. if the session is operating in a half–duplex flip–flop mode, a value of Y sends the SNA indicator CDI (Change Direction Indicator) with the current message.
SNAX/HLS Verbs SEND-DATA-Verb Formatted messages permit the exchange of binary or other unusual data. They frequently convey control information. Consult the component description of your partner to determine exactly when and where formatted data is used. When using LMO and translation, the entire FMH must be contained in the first buffer. NOTIFY–IND.
SNAX/HLS Verbs SEND-DATA-Verb USER–DATA–S is the text of the message to send. The message is not inspected in any way (control characters, binary text, and so on can be sent). However, if the message is being translated (see PROFILE TRANSLATE attribute), unexpected results might occur if binary data is translated. Note that the Format Header portion of a message is never translated. The maximum () value of this field is a value you determine.
SNAX/HLS Verbs SEND-DATA-Verb If RETURN–CODE contains any value other than those listed above, this field is undefined and should not be analyzed. USER–ERROR–CODE contains the second two bytes of SNA sense data if the SYSTEM-ERROR-CODE contains the first two bytes of SNA sense data. RETRY–ACTION–CODE is a summary indicator that indicates whether an unsuccessful request should be retried. The value returned here can be installation–defined.
SNAX/HLS Verbs SEND-DATA-Verb Your session partner has just sent ATTENTION. In this case, when convenient, your session should issue a SEND–DATA verb with PREPARE–TO–RECEIVE–IND set to Y. Your partner can now send data. Your session has just issued a SEND–DATA verb with PREPARE–TO–RECEIVE–IND set to Y. Your session partner can now send data with no further action from your session. (This is used only for HDX protocols). RESERVED–FOR–FUTURE–USE is reserved for the future.
SNAX/HLS Verbs SEND-STATUS Verb Figure 5–23 shows the SEND–DATA verb under definite response and delayed request modes. Figure 5–23.
SNAX/HLS Verbs SEND-STATUS Verb Request Format 77 VERB–SEND–STATUS pic 9(4) comp value 8. 01 SEND–STATUS–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 SENSE–TEXT. 03 SYSTEM–ERROR–CODE 03 USER–ERROR–CODE Reply Format (verb–code = 8) 01 SEND–STATUS–REPLY. 02 VERB–CODE 02 SESSION–ID 02 RETURN–CODE 02 SYSTEM–ERROR–CODE 02 USER–ERROR–CODE 02 RETRY–ACTION–CODE Return Codes RC–OK RC–INVALID–SESSION–ID RC–SESSION–FAILURE RC–POSSIBLE–DATA–LOSS RC–SEND–CHECK pic 9(4) comp. pic 9(4) comp. pic S9(4) comp. pic S9(4) comp.
SNAX/HLS Verbs SEND-STATUS Verb preface for the interpretation of these bytes. A value of %H0000 always means that USER–ERROR–CODE contains session–partner–specific data. USER–ERROR–CODE Place the second 2 bytes of the LUSTAT to be sent to the session partner in this field. The field is not inspected in any way and is not translated regardless of the PROFILE TRANSLATE attribute.
SNAX/HLS Verbs SEND-STATUS Verb Figure 5–24 shows a session example using the SEND–STATUS verb. Figure 5–24. Example of SEND–STATUS Verb REQUESTER SNAX/HLS SNALU PARTNER session established data transfer in operation ...
SNAX/HLS Verbs SET ATTRIBUTES Verb SET-ATTRIBUTES The SET–ATTRIBUTES verb allows the user of SNAX/HLS to alter dynamically a Verb subset of the PROFILE attributes. The value of TRANSLATE, LMO processing, and RESPONSE- TYPE (type of SNA response to request on chains) can be set with this verb. Request Format 77 VERB–SET–ATTRIBUTES pic 9(4) comp value 12. 01 SET–ATTRIBUTES–REQUEST. 02 VERB–CODE 02 SESSION–ID 02 REQUEST–TEXT.
SNAX/HLS Verbs SET ATTRIBUTES Verb REQUEST–TEXT contains three one–byte fields used to set the value of PROFILE attributes. TRANSLATION–INDICATOR Specifies whether partner data is to be converted. The values are Y and N. LARGE–MESSAGE–OPTION Specifies the setting of the option. The values are Y and N. RESPONSE–TYPE Specifies the DR–values for requests. The legal values are 1, 2, or 3.
SNAX/HLS Verbs SET ATTRIBUTES Verb USER–ERROR–CODE contains the second two bytes of SNA sense data if the SYSTEM-ERROR-CODE contains the first two bytes of SNA sense data. RETRY–ACTION–CODE is a summary indicator that indicates whether an unsuccessful request should be retried. The value returned here can be installation-defined.
6 Application Prototyping and Simulation (APS) System This section describes the SNAX/HLS Application Prototyping and Simulation (APS) system. APS is a SCOBOLX requester that presents one screen per SNAX/HLS verb request. Verb requests are selected by function key. The APS user selects the verb to be executed, fills in the verb indicators, directs APS to send the verb to a SNAX/HLS process, and views the result.
Application Prototyping and Simulation (APS) System are unavailable, a modem eliminator can be used to loop back the $SNAP to the $SNAT line. Such a configuration allows APS testing without an actual IBM product. The APS Pathway requester sends screens to a Tandem 6520 or 6530 terminal (not shown). The figure shows that the SNAX/HLS process must be running on the same node as the SNAX lines. A Pathway TCP running the APS requester can be remotely located in an Expand network.
Application Prototyping and Simulation (APS) System Running the Application Prototyping System (APS) Before running APS, ensure that the appropriate SNAX/HLS process is running. The examples in this section assume that the SNAX/HLS process name is $HLS and that the SNAX/HLS process server-class name is HLS. Next, ensure that the Pathway environment is running.
Application Prototyping and Simulation (APS) System Screen Layout As shown in Figure 6-2, the initial screen presented by APS is for an OPEN-SESSION verb request. Figure 6-2.
Application Prototyping and Simulation (APS) System Line 23 Lists brief labels of the functions invoked by pressing the unshifted function keys (for example, OS [an abbreviation for OPEN-SESSION]). Line 24 Lists brief labels of the functions invoked by pressing the shifted function keys (for example, USER [an abbreviation for HLS-CALL-USER]). These function keys fall into two groups: On the left are the verb keys (positions 1 through 11, shifted and unshifted).
Application Prototyping and Simulation (APS) System Executing a Verb Request Inoperative function keys are shown with no label. Table 6-1 lists the function keys, their labels, and their functions under APS. Table 6-1.
Application Prototyping and Simulation (APS) System Executing a Verb Request The SNAX/HLS server executes the verb request and returns the reply. APS formats the reply and displays it in the lower part of the screen. Visual Indication of Progress APS uses reverse video to help you know what’s happening. The function-key label for the verb on display is shown in reverse video until you press the SEND key (function key F12).
Application Prototyping and Simulation (APS) System Basic APS Function Dictionary Retry Action Displays the decimal value of RETRY-ACTION-CODE returned in the verb reply together with text. In this case, the action code (3) is a serious error, and a retry is not possible. Figure 6-3 shows these fields for an OPEN-SESSION request that completed with a syntax error. Figure 6-3.
Application Prototyping and Simulation (APS) System Basic APS Function Dictionary GA Hex Open OS PC Prnt RC RCWT RD Resp Rset SA SD Send SR SS ST User : : : : : : : : : : : : : : : : : : GET-ATTRIBUTES Verb (F10) Translate to Hexadecimal (F14) HLS-OPEN Verb (SF3) OPEN-SESSION Verb (F1) PREPARE-TO-CLOSE Verb (F2) Print Screen (F13) RECEIVE-CONTROL Verb (F4) RECEIVE–CONTROL–WAIT (SF8) RECEIVE-DATA Verb (F5) HLS-RESPOND Verb (SF6) Reset Input (F15) SET-ATTRIBUTES Verb (F11) SEND-DATA Verb (F7) Send the Verb
Application Prototyping and Simulation (APS) System ALLOCATE Verb Aloc: HLS-ALLOCATE The HLS-ALLOCATE request is used to allocate resources in SNAX/HLS that are Verb (SF2) used to manage any session you plan to open by a following HLS-OPEN request. The request identifies the name of the partner LU, the name of the PROFILE containing the rules of the session, and whether the session is a pipelined session—a property that allows more than one server process to receive data from a given session.
Application Prototyping and Simulation (APS) System ALLOCATE Verb Figure 6-4 presents a sample HLS-ALLOCATE request. To execute this verb in an APS session, display the request screen by pressing shifted F2; enter the LU-NAME, PROFILE, PIPELINE-LU-IND, and COMPLETION-MODE parameters, and press the SEND function key (F12) to cause SNAX/HLS to allocate the LU. Figure 6-4.
Application Prototyping and Simulation (APS) System ALLOCATE Verb LU Name Enter the name of the SNAX/HLS LU to be used for this session. The name must be in the format: $HLS–process–name.qualifiers the qualifiers name a specific LU and the actual entities they refer to depend on the Tandem SNA access method being used. If the access method is SNAX/XF, then qualifiers are: #SNAX/XF–line–name.LU–name If the access method is SNAX/CDF, the qualifiers are: #CDF–process–name.
Application Prototyping and Simulation (APS) System CLOSE Verb Clos: HLS-CLOSE The HLS-CLOSE request is used to terminate communication with your session Verb (SF4) partner. Unlike the CLOSE-SESSION request, this does not cause the deallocation of your LU, thus making it possible to continue to receive operator messages. If you allocated and opened your session with HLS-ALLOCATE and HLS-OPEN, you must use the HLS-CLOSE and HLS-DEALLOCATE verbs to close and deallocate the session.
Application Prototyping and Simulation (APS) System CLOSE Verb Figure 6-5 presents a sample HLS-CLOSE request. Figure 6-5.
Application Prototyping and Simulation (APS) System CLOSE Verb Close Reason Enter the value 1 or 14 in this field. HLS-CLOSE Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by a standard label for the return code. System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by a standard label.
Application Prototyping and Simulation (APS) System CLOSE SESSION Verb CS: CLOSE-SESSION Verb (F3) This verb causes the session between the requester thread and the LU to be terminated. The verb can be used only on those sessions that were opened by the OPEN-SESSION verb, rather than the HLS-ALLOCATE and HLS-OPEN verbs. To execute this verb in an APS session, display the request screen by pressing F3. There are no parameters to enter on the request screen.
Application Prototyping and Simulation (APS) System CLOSE SESSION Verb CLOSE-SESSION Request Screen Description SESSION-ID Is the session ID of the current APS session. This field is assigned automatically by APS and is not modifiable by the APS user. CLOSE-SESSION Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by a standard label for the return code. System Error Is a computational qualifier for RETURN-CODE.
Application Prototyping and Simulation (APS) System DEALLOCATE Verb Deal: The HLS-DEALLOCATE request is used to deallocate the session. If the session is not HLS-DEALLOCATE yet closed (data traffic is still possible), it is closed for you. This step is the final step in Verb (SF5) the life of a session. Any messages queued to the session no longer are accessible to your program.
Application Prototyping and Simulation (APS) System DEALLOCATE Verb HLS-DEALLOCATE Request Screen Description SESSION-ID Is the session ID of the current APS session. This field is assigned automatically by APS and is not modifiable by the APS user. Completion Mode Specifies how the verb is to be completed. In this field you must place either Q or W. Q selects the queued completion mode. This directs SNAX/HLS to complete your verb immediately with a special completion code RC-FORTHCOMING.
Application Prototyping and Simulation (APS) System DEALLOCATE Verb Exit: Exit APS (F16) Selection of the EXIT function causes the Pathway TCP to stop the APS program running on the user’s terminal. If a session is still allocated when you select the EXIT function, what happens to it depends upon what happens to the Pathway TCP program and any server links it maintains to SNAX/HLS.
Application Prototyping and Simulation (APS) System FLOW CONTROL Verb Flow: The HLS-FLOW-CONTROL screen directs SNAX/HLS to send one of four different HLS-FLOW-CONTROL specialized messages to your partner. The possible messages are shown in Table 6-2. Verb (SF7) Table 6-2.
Application Prototyping and Simulation (APS) System FLOW CONTROL Verb HLS-FLOW-CONTROL Request Screen Description SESSION-ID Is the session ID of the current APS session. This field is assigned automatically by APS and is not modifiable by the APS user. HLS-FLOW-CONTROL Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is a computational qualifier for RETURN-CODE.
Application Prototyping and Simulation (APS) System GET ATTRIBUTES Verb GA: GET-ATTRIBUTES The GET-ATTRIBUTES request returns information on the current values of PROFILE Verb (F10) options and BIND options for the current session ID. The intended use of this verb is to allow users of SNAX/HLS to inquire and dynamically set (by the SETATTRIBUTES verb) certain PROFILE options. Two types of request are defined. Request type 1 allows a user to inquire about the value of PROFILE options.
Application Prototyping and Simulation (APS) System GET ATTRIBUTES Verb Figure 6-10 shows sample BIND information (type 2 request). Figure 6-10.
Application Prototyping and Simulation (APS) System GET ATTRIBUTES Verb If RETURN-CODE is RC-SYNTAX-ERROR, SYSTEM-ERROR-CODE indicates the ordinal position of the parameter in error discounting the verb code and session ID. User Error Is a qualifier for SYSTEM-ERROR-CODE unused in this request. Retry Action Indicates whether an unsuccessful request should be retried. The screen line displays the decimal value for this indicator followed by text.
Application Prototyping and Simulation (APS) System GET ATTRIBUTES Verb Common Protocol Displays the value of the common FM protocol flags in hexadecimal notation. This value is derived from bytes 6 and 7 of the BIND record. Send Max RU Displays the maximum RU size in bytes for data sent by the SNAX/HLS server on behalf of this APS session. If LMO is not in effect, the value of this parameter is transparent to the APS session.
Application Prototyping and Simulation (APS) System OPEN Verb Open: HLS-OPEN Verb The HLS-OPEN request is used to establish communication with your session partner. (SF3) This verb follows an HLS-ALLOCATE verb that allocated the session ID, identified the name of the partner, and specified, by the PROFILE name, the options that govern the session.
Application Prototyping and Simulation (APS) System OPEN Verb Figure 6-11 presents a sample HLS-OPEN request. Figure 6-11.
Application Prototyping and Simulation (APS) System OPEN Verb Q selects the queued completion mode. This directs SNAX/HLS to complete your verb immediately with a special completion code RC-FORTHCOMING. However, the activities or actions you have requested continue. When they are completed, a queued completion notice is enqueued to your receive queue. You can sense them with RECEIVE-CONTROL, or wait for them with RECEIVE-DATA or RECEIVE-CONTROL-WAIT. The letter W selects the waited completion mode.
Application Prototyping and Simulation (APS) System OPEN Verb HLS-OPEN Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text.
Application Prototyping and Simulation (APS) System OPEN SESSION OS: OPEN-SESSION The OPEN-SESSION request is used to establish an APS session. This request is often Verb (F1) the first executed verb in an APS work session. Note, however, that the HLSALLOCATE and HLS-OPEN verbs provide enhanced functions for opening a session. The execution of this verb depends on the PROFILE options in effect.
Application Prototyping and Simulation (APS) System OPEN SESSION Figure 6-12 presents a sample OPEN-SESSION request. Figure 6-12.
Application Prototyping and Simulation (APS) System OPEN SESSION If the access method is SNAX/XF, then qualifiers are: #SNAX/XF–line–name.LU–name If the access method is SNAX/CDF, the qualifiers are: #CDF–process–name.openname–of–SNAX/CDF–appl Profile Specifies the name of a valid PROFILE record in the current RDT. The name is converted to uppercase by the SNAX/HLS server. Appl Specifies the name of the application.
Application Prototyping and Simulation (APS) System OPEN SESSION System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text. If RETURN-CODE is RC-SYNTAX-ERROR, the SYSTEM-ERROR-CODE indicates the ordinal position of the parameter in error discounting the verb code and session ID.
Application Prototyping and Simulation (APS) System PREPARE TO CLOSE Verb PC: PREPARE-TO-CLOSE Verb The PREPARE-TO-CLOSE verb is used to terminate a session in an orderly fashion. Use of this verb is encouraged to ensure that both session partners are aware that a session is about to be terminated, thus allowing each to perform clean-up processing. This verb has no parameters. Select the verb by pressing function key F2 and execute the verb by pressing SEND (F12).
Application Prototyping and Simulation (APS) System PREPARE TO CLOSE Verb Figure 6-13 shows a sample screen. Figure 6-13.
Application Prototyping and Simulation (APS) System PREPARE TO CLOSE Verb PREPARE-TO-CLOSE Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL Verb RC: The RECEIVE-CONTROL request is intended as a nowait check of the user’s receive RECEIVE-CONTROL queue. In other words, the RECEIVE-CONTROL verb causes SNAX/HLS to examine Verb (F4) the top element of the receive queue. If the receive queue is empty, the verb is completed with RC-NO-DATA-AVAILABLE.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL Verb Figure 6-14 shows a sample screen. Figure 6-14.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL Verb System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by a standard label. If RETURN-CODE is RC-SYNTAX-ERROR, the SYSTEM-ERROR-CODE indicates the ordinal position of the parameter in error discounting the verb code and session ID.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL Verb Comp (MESSAGE-COMPLETE-IND) A value of Y indicates that the current message in the user buffer is a complete user message (although the message could be truncated if RC-DATATRUNCATED is returned). A value of N can be returned only under the LMO feature and indicates that subsequent RECEIVE-DATA verbs retrieve more elements of the session partner’s message.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL Verb This message implies that your partner is waiting for an RTR message before it tries to send the transaction again. bind_cinit_data This provides the information conveyed on the BIND or CINIT message that began the session. It enables your application to examine the user-data field. You see this data message only if the WANT-BIND-DATA PROFILE attribute is set to USER-DATA or ALL.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL Verb partner_data The message is a data message from the session partner. request_close The session partner requests session closure. session_closed This identifies the specific SNA event that led to the closure of the session. You see this message only if you opened the session with the HLS-ALLOCATE and HLS-OPEN verbs. signal The session partner has sent an SNA SIG request.
Application Prototyping and Simulation (APS) System RECEIVE CONTROL WAIT Verb RCWT: RECEIVE-CONTROL-W AIT Verb (SF8) The RECEIVE-CONTROL-WAIT verb remains outstanding until a message is available for the APS session. The format of the reply is the same as would have been received had a RECEIVE-CONTROL verb request been issued with the same message at the top of the receive queue for the APS session. If there is no message on the receive-queue, the APS screen hangs until data is available.
Application Prototyping and Simulation (APS) System RECEIVE DATA Verb RD: RECEIVE-DATA The RECEIVE-DATA request causes the top element of the receive-queue for the APS Verb (F5) session to be retrieved and displayed. If there is no message on the receive queue, the APS screen hangs until data is available. If this situation causes a deadlock, use the HLSCOM QMSG command to send an interrupt message to the APS application. There are three formats for verb replies to RECEIVE-DATA: 1.
Application Prototyping and Simulation (APS) System RECEIVE DATA Verb RECEIVE-DATA Request Screen Description SESSION-ID Is session ID of the current APS session. This field is assigned automatically by APS and is not modifiable by the APS user. RECEIVE-DATA Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is a computational qualifier for RETURN-CODE.
Application Prototyping and Simulation (APS) System RECEIVE DATA Verb TIP (TRANSACTION-IN-PROGRESS-IND) A value of Y indicates that you are in bracket state (a unit of work). If the current session PROFILE does not use brackets, the value is N. Comp (MESSAGE-COMPLETE-IND) A value of Y indicates that the current message in the user buffer is a complete user message (although the message could be truncated if RC-DATATRUNCATED is returned).
Application Prototyping and Simulation (APS) System RECEIVE DATA Verb bid_rejected This indicates that a negative response (value 0814) was sent to your partner. It occurs only if your half-session has assumed control of bid rejects with the PROFILE specifying USER for the BID-REJECTION option. This message implies that your partner is waiting for an RTR message before it tries to send the transaction again.
Application Prototyping and Simulation (APS) System RECEIVE DATA Verb prepared_to_close The session partner is prepared to terminate the session in an orderly fashion. You are expected to issue a PREPARE-TO-CLOSE verb. partner_data The message is a data message from the session partner. request_close The session partner requests session closure. session_closed This identifies the specific SNA event that led to the closure of the session.
Application Prototyping and Simulation (APS) System RESPOND Verb Resp: HLS-RESPOND The HLS-RESPOND request directs SNAX/HLS to send a response to a partner-data Verb (SF6) message previously sent to you. The request is valid only if the PROFILE attribute USER-RESPONSES is set You can respond to requests only if the RECEIVE-DATA operation completed with the DRI indicator bearing a value other than 0.
Application Prototyping and Simulation (APS) System RESPOND Verb Message Tag Specifies the sequence number of the message to which you are responding. This value is derived from the recovery tags of the received data item. Sense Data Specifies the two sense-data values to be sent. These values are sent only with negative responses. The data you enter here is in hexadecimal. HLS-RESPOND Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text.
Application Prototyping and Simulation (APS) System SET ATTRIBUTE Verb SA: SET-ATTRIBUTES The SET-ATTRIBUTES request allows the APS user to dynamically change selected Verb (F11) options of the current PROFILE. The setting of data translation, type of SNA response, and a large message option (LMO) can be affected by this verb. Figure 6-17 shows a sample screen. The SET-ATTRIBUTES request affects only verbs executed subsequent to the SETATTRIBUTES request.
Application Prototyping and Simulation (APS) System SEND DATA Verb Translation Ind Specifies the new setting of the TRANSLATE PROFILE attribute for this session. A value of N instructs SNAX/HLS not to perform any data translation on send and receive verb functions. A value of Y instructs SNAX/HLS to translate all user data sent or received. Large Message Option Specifies the new setting of the LMO PROFILE attribute for this session.
Application Prototyping and Simulation (APS) System SEND DATA Verb Note that the completion of the SEND-DATA verb depends on the session BIND. If the session is bound with immediate request mode and definite responses are used, the SEND-DATA verb completes when a response has been received from the session partner. (If two APS sessions are communicating through a loopback, the message is received by a RECEIVE-DATA verb.
Application Prototyping and Simulation (APS) System SEND DATA Verb performance, you should set this indicator whenever you wish to receive data in response to the current message. If the session is operating in full-duplex send/receive mode, the indicator is ignored. End Txn (END-TRANSACTION-IND) A value of Y sends the SNA indicator EBI (end bracket indicator). This terminates the current bracket (unit of work).
Application Prototyping and Simulation (APS) System SEND DATA Verb SEND-DATA Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text.
Application Prototyping and Simulation (APS) System SEND the Verb Send: Send the Verb The SEND function key causes the verb request displayed on the screen to be sent to (F12) SNAX/HLS for execution. The emphasis on the verb function-key label moves to the F12/SEND label, a verb request is sent to the SNAX/HLS server, a verb reply is accepted from the SNAX/HLS server, and the verb reply is displayed. The APS screen is locked for the duration of the verb execution.
Application Prototyping and Simulation (APS) System SEND AND RECEIVE Verb SR: SEND-AND-RECEIVEDATA Verb (F9) The SEND-AND-RECEIVE-DATA request is a composite verb. Following are the request functions: A SEND-DATA screen is presented to the APS user. The APS user enters all appropriate parameters for the SEND-DATA request. The SEND (F12) function is executed to send the request to the SNAX/HLS server for execution.
Application Prototyping and Simulation (APS) System SEND STATUS Verb SS: SEND-STATUS The SEND-STATUS request causes SNAX/HLS to send the SNA LUSTAT message. Verb (F8) LUSTAT allows two session partners to exchange status. Some LUSTATs are reserved by SNA and others are available for use by any session partner. See the SNA references listed in “About This Manual” for more information on SNA status messages. Figure 6-19 shows a sample screen. Figure 6-19.
Application Prototyping and Simulation (APS) System SEND STATUS Verb SEND-STATUS Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text.
Application Prototyping and Simulation (APS) System REQUEST SEND STATE Verb ST: REQUEST-SEND-STAT E Verb (F6) REQUEST-SEND-STATE causes SNAX/HLS to send the SNA message SIG that requests the session partner to enter receive state so that the sender of SIG can send data. Use this verb when you have entered receive state but wish to transmit data to the session partner. You must wait until the ESS indicator is set to Y on a RECEIVEDATA verb before sending data.
Application Prototyping and Simulation (APS) System REQUEST SEND STATE Verb System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text. If RETURN-CODE is RC-SYNTAX-ERROR, the SYSTEM-ERROR-CODE indicates the ordinal position of the parameter in error discounting the verb code and session ID.
Application Prototyping and Simulation (APS) System CALL USER Verb User: HLS-CALL-USER The HLS-CALL-USER request is used to pass information to and from any Verb (SF1) customization routines that are installed with SNAX/HLS. If no such routines have been installed (your systems manager will know), this request is ignored by SNAX/HLS. Otherwise, your installation’s customization routines can interact with the verb, both upon issue and upon reply.
Application Prototyping and Simulation (APS) System CALL USER Verb Figure 6-21 presents a sample HLS-CALL-USER request. Figure 6-21.
Application Prototyping and Simulation (APS) System CALL USER Verb Length Defines the length of the text. HLS-CALL-USER Reply Screen Description Return Code Displays the value of the verb reply RETURN-CODE in decimal followed by text. System Error Is a computational qualifier for RETURN-CODE. This screen line displays the SYSTEM-ERROR-CODE value of the verb reply—first in decimal, next in hexadecimal, and followed by text.
Application Prototyping and Simulation (APS) System Advanced APS Functions Advanced APS In loop-back testing, SNAX/HLS verb dynamics can be shown with simple messages. Functions However, in testing to IBM devices (for example, 3624) or IBM subsystems (for example, CICS/IMS), simple messages might not be sufficient to test a total application. The advanced functions of APS address the needs of this type of testing.
Application Prototyping and Simulation (APS) System Advanced APS Functions Using Hexadecimal Data With Reply Data When any reply carrying user data is visible (RECEIVE-DATA and HLS-CALL-USER), you can use the Hex function key (F14) to display the data in hexadecimal. After the Hex key is pressed, the screen display changes similar to that shown in Figure 6-22. Note that the reply area is divided into two parts. The left section shows the message from the session partner in hexadecimal.
Application Prototyping and Simulation (APS) System Advanced APS Functions Figure 6-23. Hex Subfunction for SEND-DATA Request T9089C00 SNAX/HLS Application Prototype Simulator (APS) Request: send_data ADDR 01 21 41 61 1 61626364 20202020 41424344 20202020 5 65202020 20202020 45202020 20202020 Session ID: 9 Hex 20202020 20202020 20202020 20202020 13 20202020 20202020 20202020 20202020 15 Jul 91 a20 2 17 20202020 20202020 20202020 20202020 ....|....|ASCI|....
7 Customization In certain specialized applications, you might wish to intervene in the normal flow of traffic on a session; for example, you might have to edit data or accumulate and report performance statistics. SNAX/HLS provides the ability to customize the product by allowing installation-written routines to be invoked at certain critical processing points. These routines are sometimes called user-exit routines.
Customization Storage Available to Customization Routines Storage Available to Customization routines can use part of extended storage, which is allocated at the User Exit Routines request of your SNAXHLS^USEREXIT^ENABLE routine (this routine can also preset the storage to any desired values). SNAX/HLS then passes the storage address whenever it invokes a customization routine. If no storage is allocated, it is appropriate to use the address passed, as it would result in SNAX/HLS abending with a trap.
Customization Programming Constraints TAL Copybook Definitions The TAL module, HLSDDT, contains definitions for the data structures needed by the customization routines. You include these definitions in your TAL source code using the following statement: ?SOURCE HLSDDT( USEREXITS ) To ensure that your data structures are compatible with those of the latest version of SNAX/HLS, you are strongly discouraged from copying the supplied data structures or defining them yourself.
Customization HLS-CALL-USER Verb HLS-CALL-USER Verb The HLS-CALL-USER verb allows an application program to send information to your customization SNAXHLS^USEREXIT^VERB^IN routine and to get information from your customization SNAXHLS^USEREXIT^VERB^OUT routine. The HLS-CALLUSER request provides two integer arguments and a variable-length text string that are presented to your SNAXHLS^USEREXIT^VERB^IN routine.
Customization HLS-CALL-USER Verb Request Format 77 VERB-HLS-CALL-USER pic 9(4) comp value 13. 01 HLS-CALL-USER-REQUEST. 02 02 02 02 02 VERB-CODE SESSION-ID COMPLETION-MODE REQUEST-FORMAT ARGUMENTS. 03 ARGUMENT 02 USER-DATA-LENGTH 02 USER-TEXT-S pic pic pic pic 9(4) comp. 9(4) comp. X. (I) X value space. pic S9(4) comp occurs 2 times. pic 9(4) comp. pic X occurs 0 to times depending on USER-DATA-LENGTH. Reply Format (verb-code = 13) 01 02 02 02 02 02 02 02 HLS-CALL-USER-REPLY.
Customization HLS-CALL-USER Verb Request Details VERB-CODE identifies which verb is being issued. In SCOBOLX, you should issue the statement: MOVE VERB-HLS-CALL-USER TO verb-code OF request-header. In TAL, you should issue the statement: STRUCT .rq(request^header); ... rq.verb^code := VERB^HLS^CALL^USER; SESSION-ID contains 0 or a valid session ID. COMPLETION-MODE specifies how you want to be notified of the completion of the request. The only option supported is: I Immediate Response.
Customization HLS-CALL-USER Verb USER-DATA-S contains text that is available to the SNAXHLS^USEREXIT^VERB^IN routine. Unless the user’s routine saves the information privately, this text is not available to the SNAXHLS^USEREXIT^VERB^OUT routine. You should determine a max value based on the largest amount of data that you want to send or receive from the user-exit routines. Reply Details VERB-CODE identifies the reply being returned and contains the integer value 13.
Customization HLS-CALL-USER Verb RETURN-CODE is a computational (that is, binary) field that indicates the success or failure of the operation requested. The return condition of RC-OK indicates success. The possible error responses are explained below. A full discussion of the error codes is in Appendix A of the SNAX/HLS Diagnosis and Support Manual. SYSTEM-ERROR-CODE is a modifier to the return code.
Customization Data Structures Data Structures The data structures defined below are accessible in the file HLSDDT distributed with SNAX/HLS. The relevant section is USEREXITS, which defines the structures SNAXHLS^USEREXIT^IN^BLOCK and SNAXHLS^USEREXIT^OUT^BLOCK. To ensure compatibility, you should use these definitions in your customization routines.
Customization Data Structures The SNAXHLS^USEREXIT^OUT^BLOCK Structure SNAXHLS^USEREXIT^OUT^BLOCK is used by your enabling routine to return operating parameters to SNAX/HLS. The block contains the information defined below. Further information might eventually be added to the end of the block by the developer (thus preserving compatibility). Your customization enabling routine indicates in the first word the number of bytes it is setting.
Customization Data Structures The SNAXHLS^USEREXIT^VERB^BLOCK Structure The SNAXHLS^USEREXIT^VERB^BLOCK structure is passed to the customization SNAXHLS^USEREXIT^VERB^IN routine (on verb arrival) and to the customization SNAXHLS^USEREXIT^VERB^OUT routine (on verb reply). This block permits these routines to identify the issuer of the verb being examined.
Customization Data Structures In cases where SNAX/HLS is does provide the above information, the field contains a unique five-word identification of the issuing process. Installations must not attempt to decipher this field in such cases and should instead use the fields described below if similar information is required.
Customization Data Structures The BIND^TEMPLATE Structure The BIND^TEMPLATE structure can be used by the SNAXHLS^USEREXIT^VRFY^BIND^RSP customization routine to parse the BIND request passed as a parameter. ..
Customization Data Structures Accessing Storage The address of the structure allocated by your enabling routine is passed to the other customization routines whenever they are called. The following fragment of code demonstrates the correct usage: STRUCT UserData(*); BEGIN INT varb1; INT varb2; ... END; ... PROC SNAXHLS^USEREXIT^SNAX^OUT(wsadr, sessid, vbufr, vlen); INT(32) wsadr; INT sessid; STRING .EXT vbufr; INT .EXT vlen; BEGIN STRING .EXT ud(UserData) := wsadr; ! (*) ... ud.varb1 := 9; ud.varb2 := ud.
Customization Procedure Specifications Procedure Specifications The following subsections present the syntax for the following routines: SNAXHLS^USEREXIT^ENABLE SNAXHLS^USEREXIT^VERB^IN SNAXHLS^USEREXIT^VERB^OUT SNAXHLS^USEREXIT^SNAX^IN SNAXHLS^USEREXIT^SNAX^OUT SNAXHLS^USEREXIT^VRFY^BIND^RSP SNAXHLS^USEREXIT^VRFY^STSN^RSP The USEREXIT^ENABLE Routine The SNAXHLS^USEREXIT^ENABLE routine is invoked by SNAX/HLS at startup in order to allocate and preset working storage for the other customization routines
Customization Procedure Specifications where the size is an integer count of bytes to be allocated. The value can be any value in the range 0 through 32,767. On return, SNAX/HLS provides a 32-bit extended address for the storage just allocated. If you supply a size of 0 or do not call the procedure, no storage is allocated, and the value %HFE000000%D is returned. Only one call to the allocator procedure should be made. Thus, only one block of dynamic storage is allocable.
Customization Procedure Specifications When your routine is called, the verb is not processed or checked by SNAX/HLS. In particular, the verb code might be invalid, the session ID might refer to a nonexistent session, and so on. It is therefore necessary that you check all values for relevance. Typically, your routine extracts information from the verb request (such as the verb code and other application data) and saves it in the session-specific storage area previously allocated.
Customization Procedure Specifications vbufr gives the address of the verb-reply text as a 32-bit extended address. You can use the definitions in the module HLSDDT to obtain the structure definitions. For example, you can view the area in a RECEIVE-DATA response as follows: STRING .EXT rcv^data(receive^data^reply) := @vbufr; vlen defines the length (in bytes) of the verb reply that SNAX/HLS is about to return to the user. You can modify this value if you change the length of the verb reply.
Customization Procedure Specifications The USEREXIT^SNAX^IN Routine The SNAXHLS^USEREXIT^SNAX^IN routine is invoked when SNAX/HLS has just received input (response or request) from the Tandem SNA access method, for example SNAX/XF (but only if thus enabled by your enabling routine). This allows the customization routine to inspect and perhaps modify the input before SNAX/HLS processes it.
Customization Procedure Specifications The USEREXIT^SNAX^IN routine can be used as part of response-time statistics collection. You can examine the message, verify that it is SNA message needed, and record a value in the session-specific storage. You might also use this routine to change the text of an SNA message. However, you must be very careful in doing this, since a wrong modification can cause unpredictable results in the protocol handling.
Customization Procedure Specifications snu points to the SNALU buffer using extended addressing. vlen defines the length (in bytes) of the messages about to be sent to the SNALU interface. In case of requests, you can only reduce this value although it should not be reduced to below 9 bytes. For responses, the value can be increased to a maximum of 265 bytes. No attempt should be made to reduce it below 9 bytes. The USEREXIT^SNAX^OUT routine can be used as part of response-time statistics collection.
Customization Procedure Specifications The USEREXIT^VRFY^BIND^ RSP Routine The SNAX^HLS^USEREXIT^VRFY^BIND^RSP routine is invoked when SNAX/HLS has just finished processing the BIND request and is about to send a positive response. This customization routine allows the inspection of any field in the BIND request, and rejection of the BIND request with user-supplied SNA sense data.
Customization Procedure Specifications bind^rq points to the BIND RU received by SNAX/HLS. bind^rq^len defines the length (in bytes) of the BIND RU received by SNAX/HLS. Note that this excludes the SNAX header, and can be in the range of 1 through 256. bind^rsp points to the positive BIND response built by SNAX/HLS. bind^rsp^len defines the length (in bytes) of the positive BIND response built by SNAX/HLS. Note that this excludes the SNAX header, and can be in the range of 1 through 256.
Customization Procedure Specifications The USEREXIT^VRFY^STSN^ RSP Routine The SNAXHLS^USEREXIT^VRFY^STSN^RSP routine is invoked when SNAX/HLS has just finished processing the STSN (set and test sequence number) request and is about to send a positive response. This customization routine allows the inspection of any field of the STSN request, and modification of the positive response that SNAX/HLS is about to send.
Customization Procedure Specifications stsn^rq points to the STSN RU received by SNAX/HLS. appl^send^seq^no defines the sequence number maintained in the half-session control block, if the VERIFY-SEQUENCE-NUMBERS-IND on the OPEN-SESSION or the HLS-OPEN verb is sent to N, or the RCV_SEQUENCE_NUMBER passed on the OPENSESSION or HLS-OPEN verb if it is set to Y. stsn^rsp points to the positive STSN response built by SNAX/HLS.
Customization Sample Customization Routines Sample Customization The following sample program demonstrates a simple use of customization routines. Routines The problem proposed is to change a BIND protocol from definite or exception responses to definite responses only. It is assumed that the half-session managed by SNAX/HLS is an SLU. Note This problem arose in connection with earlier versions of SNAX/HLS, which did not allow for user control of the kind of responses used.
Customization Sample Customization Routines USEREXIT^ENABLE Routine ?SOURCE hlsddt(UserExits) !--------------------------------------------------------PROC SnaxHLS^UserExit^Enable(InBlock, OutBlock, Allocator); INT .EXT InBlock (SNAXHLS^UserExit^In^Block); INT .EXT OutBLock (SNAXHLS^UserExit^Out^Block); INT(32) PROC Allocator; BEGIN ! ! Note that the OutBlock is guaranteed preset at call to ! xhave all defaulted values. ! ! For Solution 1, we enable SNAX^IN. ! For solution 2, we enable SNAX^OUT.
Customization Sample Customization Routines USEREXIT^VERB^IN Routine PROC SNAXHLS^USEREXIT^VERB^IN (wsadr, vblock, vbufr, vlen); INT(32) wsadr; INT .EXT vblock(snaxhls^userexit^verb^block); STRING .EXT vbufr; INT .EXT vlen; BEGIN END; USEREXIT^VERB^OUT PROC SNAXHLS^USEREXIT^VERB^OUT(wsadr, vblock, vbufr, vlen); INT(32) wsadr; INT .EXT vblock(snaxhls^userexit^verb^block); STRING .EXT vbufr; INT .
Customization Sample Customization Routines USEREXIT^SNAX^IN Routine PROC SNAXHLS^USEREXIT^SNAX^IN (wsadr, sessid, snu, vlen); INT(32) wsadr; INT sessid; STRING .EXT snu; INT .EXT vlen; BEGIN !---------------------------! ! For solution #1 only ! !---------------------------! ! ! To recognize a BIND command, we must test several ! flags, summarized as follows: ! rh = 011x xxxx, and request code = %H31 IF (snu[6] LAND %HE0) = %h60 AND snu[9] = %H31 THEN snu[14].
Customization Sample Customization Routines USEREXIT^SNAX^OUT Routine PROC SNAXHLS^USEREXIT^SNAX^OUT (wsadr, sessid, snu, vlen); INT(32) wsadr; INT sessid; STRING .EXT snu; INT .EXT vlen; BEGIN !---------------------------! ! For solution #2 only ! !---------------------------! ! ! The RUs that we change from exception to definite ! responses are isolated below: ! The isolation insists that the bit configuration ! in the RH be as ! 000x xxx1 (RRI=0,CTGY=0,ECI=1) ! IF (snu[6] LAND %HE1) = %H01 THEN snu[7].
Customization Sample Customization Routines USEREXIT^VRFY^ BIND^RSP The following sample routine illustrates the use of the SNAXHLS^USEREXIT^VRFY^BIND^RSP customization routine. The user-exit routine rejects all BIND requests with a sense data of %h0821, if the PLU application name does not match one of the possible values for this session (identified by the profile name).
Customization Sample Customization Routines USEREXIT^VRFY^ STSN^RSP The following sample routine illustrates the use of the SNAX^HLS^USEREXIT^VRFY^STSN customization routine. This user-exit routine sets bits 0 and 1 in the result code to %b10. If an STSN request is received with action code SET and the sequence number in the request differs from the application sequence number by more that 17 on the send flow (i.e.
Customization Sample Customization Routines PROC SNAXHLS^USEREXIT^VRFY^STSN^RSP (wsdar, sessid, profile^name, stsn^rq, appl^send^rq^no, appl^rcv^seq^no, stsn^rsp, stsn^rsp^len); INT (32) wsadr; INT sessid; STRING .EXT profile^name; STRING .EXT stsn^rq (stsn^template); INT appl^send^rq^no; INT .EXT appl^rcv^seq^no; STRING .EXT appl^rcv^seq^no (stsn^template); INT .EXT stsn^rsp^len; BEGIN INT rq^send^seq^no, rq^rcv^seq^no; LITERAL SET = %H01; DEFINE send^action^code = stsn^rq.action^result^code.
Customization Sample Customization Routines (This 7–34 page left intentionally blank) 104707 Tandem Computers Incorporated
Appendix A Supplemental Information for D-Series Systems This appendix provides specific information about D-series SNAX/HLS relevant to the SNAX/HLS Application Programming Manual.
Supplemental Information for D-Series Systems (This page left intentionally blank) A–2 104707 Update 1 to 064393 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 PATHS paragraph. A paragraph within the SYSGEN configuration file that is used to redefine each controller name to a path name that is unique to the system. PDN. Public data network. 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.
Glossary secondary logical unit (SLU). One of the two LUs involved in a LU-LU session. The SLU functions under the control of the remote PLU. It accepts an incoming BIND request from the PLU. 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.
Glossary SSCP–PU. In SNA, a session between an SSCP and a PU that allows the SSCP to send requests to and receive status information from individual nodes in order to control the network configuration. 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.
Glossary configuring the system, generating the operating system, and installing the operating system. Systems Network Architecture Communications Services/Cross Domain facility (SNAX/CDF). A Tandem software product that allows procedures running in a Tandem System to communicate with LUs in other SNA domains. 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.
Glossary (This page left intentionally blank) Glossary–10 104707 Tandem Computers Incorporated
Index A Acknowledgement of data 3-5 Allocating the half session 3-1, 3-2 APS environment preparation 6-2 error information in replies 6-7 example environment 6-1 function dictionary 6-8 function key assignments table of 6-6 Function Key Usage 6-66 hexadecimal with reply data 6-67 hexadecimal with request data 6-67 running APS 6-3 screens 6-4 verb requests 6-6 APS functions advanced 6-66 Aloc HLS-ALLOCATE verb (SF2) 6-10 Clos HLS-CLOSE Verb (SF4) 6-13 CS CLOSE-SESSION Verb (F3) 6-16 Deal HLS-DEALLOCATE Verb
Index APS functions (continued) PC PREPARE-TO-CLOSE Verb 6-35 Prnt Print Screen (F13) 6-37 RC RECEIVE-CONTROL Verb (F4) 6-38 RD RECEIVE-DATA Verb (F5) 6-45 Resp HLS-RESPOND Verb (SF6) 6-50 Rset Reset Input (F15) 6-51 SA SET-ATTRIBUTES Verb (F11) 6-52 SD SEND-DATA Verb (F7) 6-53 Send Send the Verb (F12) 6-57 SR SEND-AND-RECEIVE-DATA Verb (F9) 6-58 SS SEND-STATUS Verb (F8) 6-59 ST REQUEST-SEND-STATE Verb (F6) 6-61 User HLS-CALL-USER Verb (SF1) 6-63 C CLOSE procedure TAL 1-17 Close session enhanced 3-3 orderl
Index Communication closing with session partner 3-2 opening with partner 3-2 Completion mode immediate 4-1 queued 4-2 waited 4-2 Connection types 2-1 Contention in half-duplex sessions 3-9 CONTROL procedure TAL 1-17 CONVERT-ERROR-CODE verb 5-4 use of 3-7 Copybooks for customization routines 7-3 Customization routines accessing storage 7-14 data structures 7-8 examples 7-26 global storage 7-2 installation 7-2 programming constraints 7-3 purpose 7-1 SNAXHLS^USEREXIT^ENABLE 7-1, 7-15 SNAXHLS^USEREXIT^SNAX^IN
Index DATA^TYPE^DEFINITIONS TAL 1-14 Deallocation half session 3-2 Delayed request mode 3-8 DR^NAMS 1-16 E Enhanced verbs versus simple verbs 3-4 Environment for APS 6-2 Error information in APS replies 6-7 Exit from APS 6-20 Extended storage and customization routines 7-2 F Formats for replies 4-6 for requests 4-5 Function dictionary APS 6-8 Function key assignments table for APS 6-6 Function keys terminal in APS 6-4 usage in APS 6-66 G GET-ATTRIBUTES verb 5-7 in APS 6-23 Index–4 104707 Tandem Computers
Index H Half session allocating the 3-1 deallocating of 3-2 Headers reply 4-6 request 4-5 Hexadecimal in APS reply data 6-67 in APS request data 6-67 translation in APS 6-26 HLS-ALLOCATE verb 5-12 in APS 6-10 use of 3-1 HLS-CALL-USER verb 7-4 HLS-CLOSE verb 5-17 in APS 6-13 use of 3-1 HLS-DEALLOCATE verb 5-22 in APS 6-18 use of 3-1, 3-2 HLS-FLOW-CONTROL verb 5-25 in APS 6-21 use of 3-6 HLS-OPEN verb 5-32 in APS 6-27 use of 3-1, 3-3 HLS-RESPOND verb 5-43 in APS 6-50 use of 3-4 HLSDDS SCOBOLX copybook 1-1 HL
Index I Immediate completion mode 4-1 Immediate request mode 3-8 Interface standard verb 4-1 L Languages other 1-20 LARGE-MESSAGE-OPTION verb 3-5 use of 3-7 LMO 3-10 See also LARGE-MESSAGE-OPTION verb LUs pipelined 3-3 N notification 3-10 Notification of receipt 3-8 O OPEN procedure TAL 1-19 Open session enhanced 3-3 simple 3-3 OPEN-SESSION verb 5-47 in APS 6-31 use of 3-1 P Partner See Session partner PREPARE-TO-CLOSE verb use of 3-2 PATHWAY required for APS 6-2 Pipelined LUs 3-3 Index–6 104707 Tandem C
Index PREPARE-TO-CLOSE verb 5-53 in APS 6-35 use of 3-6 Print Screen in APS 6-37 Q Queued completion mode 4-2 R RC-SEND-CHECK return code treatment of 3-9 RC^NAMSSection RC^NAMS 1-14 RECEIVE-CONTROL verb 5-58 in APS 6-38 use of 3-6 RECEIVE-DATA verb 5-80 in APS 6-45 use of 3-4 RECEIVE-CONTROL-WAIT verb 6-44 Replies additional building blocks 1-4 format of 4-6 Reply codes 187 1-17 189 1-17 Reply definitions SCOBOLX 1-5 Reply format 4-6 Reply header 4-6 Request definitions SCOBOLX 1-5 Request format 4-5 Requ
Index Requests format of 4-5 Reset Input key in APS 6-51 Response protocols 5-99 Return code categories 4-3 RETURN-CODE-DEFINITIONS SCOBOLX 1-2 RETURN^CODE^DEFINITIONS TAL 1-14 S SCOBOLX programming standards 1-1 server interface 1-8 terminal interface 1-8 SCOBOLX copybook interfacing 1-8 Screen printing in APS 6-37 Send verb in APS 6-57 SEND-AND-RECEIVE-DATA verb 5-95 in APS 6-58 use of 3-4 SEND-DATA verb 5-98 in APS 6-53 use of 3-4 SEND-STATUS verb 5-106 in APS 6-59 use of 3-6 Server connections 2-1 Serv
Index Session profiles in allocation 3-2 Session-specific uses of storage 7-2 Sessions contention for half-duplex 3-9 SET-ATTRIBUTES verb 5-110 in APS 6-52 Simple verbs versus enhanced verbs 3-4 SNA protocol interpretation 5-98 SNAXHLS^USEREXIT^ENABLE customization routine 7-1 example 7-27 routine 7-15 SNAXHLS^USEREXIT^IN^BLOCK structure 7-9 SNAXHLS^USEREXIT^OUT^BLOCK structure 7-10 SNAXHLS^USEREXIT^SNAX^IN customization routines 7-1 example 7-29 routine 7-19 SNAXHLS^USEREXIT^SNAX^OUT example 7-30 routine
Index Specific LU connection to 2-1 Standard verb interface 4-1 Status requests 3-6 T TAL programming standards 1-13 TAL copybook for customization routines 7-3 interfacing 1-17 Terminal function keys in APS 6-4 Terminal interface SCOBOLX 1-8 The BIND^TEMPLATE structure 7-13 The STSN^TEMPLATE structure 7-13 U USEREXITS 1-14 Utility verbs 3-7 V Verb in SCOBOLX copybook 1-2 Verb formats standard 4-5 Verb requests executing in APS 6-6 VERB-CODE-DEFINITIONS SCOBOLX 1-1 Verbs alphabetical listing 5-1 Calls for
Index Verbs (continued) HLS-ALLOCATE 5-12 HLS-CALL-USER 7-4 HLS-CLOSE 5-17 HLS-DEALLOCATE 5-22 HLS-FLOW-CONTROL 5-25 HLS-OPEN 5-32 HLS-RESPOND 5-43 OPEN-SESSION 5-47 PREPARE-TO-CLOSE 5-53 processing of 4-1 RECEIVE-CONTROL 5-58 RECEIVE-DATA 5-80 REQUEST-SEND-STATE 5-92 SEND-AND-RECEIVE-DATA 5-95 SEND-DATA 5-98 SEND-STATUS 5-106 SET-ATTRIBUTES 5-110 standard formats 4-5 standard interface 4-1 table of building blocks 1-2 TAL copybook 1-14 utility 3-7 VERB^CODE^DEFINITIONS TAL 1-13 VERB^NAMS 1-15 W Wait compl
