Table of Contents (exploded view)
Abstract for SNA Programming
Contents
Summary of changes for z/OS Version 2 Release 1
VTAM application program concepts
Systems Network Architecture (SNA) concepts in VTAM
Network accessible units
Sessions
SSCP-PU session
SSCP-LU session
Initiate request or logon
Control Initiate request
LOGON exit routine
Establishing the LU-LU session (OPNDST macroinstruction)
BIND request
Completing the LU-LU session establishment
Major programming elements in a VTAM application program
Opening the program
Establishing a session with an LU
Receiving requests from LUs
Sending a request
Sending a response
Receiving a response
Other exit routines
Terminating a session with an LU
Closing the program
Constants and control blocks
VTAM macroinstructions
VTAM application program as part of an SNA network
VTAM application program
Processing part
Communication part
VTAM part
Network control program
Logical unit
Terminal operator and devices
Another VTAM application program
Using a VTAM application program to manage the network
VTAM language
Characteristics of the language
Keyword operands
Manipulative macroinstructions
Exit routines
Summary description of the VTAM macroinstructions
Declarative macroinstructions
ACB
EXLST
NIB
RPL
Manipulative macroinstructions
GENCB
SHOWCB
TESTCB
MODCB
ACB-based macroinstructions
OPEN
CLOSE
RPL-based macroinstructions
Session-establishment macroinstructions
OPNDST
OPNSEC
REQSESS
SIMLOGON
Session-termination macroinstructions
CLSDST
SESSIONC
TERMSESS
Communication macroinstructions
RECEIVE
RESETSR
SEND
SESSIONC
Macroinstructions that assist in session establishment or communication
CHANGE
CHECK
EXECRPL
INQUIRE
INTRPRET
SETLOGON
Program operator macroinstructions
RCVCMD
SENDCMD
Relationship between the executable macroinstructions and control blocks
Opening the application program
Establishing sessions with LUs
Communicating with LUs
Terminating sessions with LUs
Closing the application program
Exit routines
Normal operating system environment for a VTAM application program
Use of a single task
Mainline program
Inline exit routines
Asynchronous exit routines
Dispatching priorities
Organizing an application program
Coding guidelines for application programs
Program structure recommendations
Simplifying migration and network upgrades
Single-thread or multithread operations
Using a single-thread program
Using a multithread program
Multithreading facilities
USERFLD field of the NIB
Scheduling output
Receiving input on any session except those already in communication
How a synchronous operation works
How an asynchronous operation works
Using ECBs
Using RPL exit routines
Initializing a session
Advantages and disadvantages of different forms of operation
Some questions that affect program organization
Application programming interface
General requirements
Specific requirements
Handling control blocks and work areas
Techniques for handling control blocks and work areas
Element per LU at assembly
Element per session at session establishment
Element per transaction
Element per request
Combinations
Opening and closing an application program
Opening an application program
Access method control block (ACB)
OPEN macroinstruction
Vector lists
Vector lists supplying information to VTAM
Vector lists supplying information to the application
The access-method-support vector list
Resource-information vector list
Supplying control vectors with the SETLOGON START
Using multiple ACBs in a VTAM application program
Using network-qualified names
Establishing network-qualified names capability
Where OPEN can be issued
Using persistent LU-LU session support
How an application establishes persistence
Session recovery states
Application program recovery with single-node persistence enabled
Response to an application failure with single-node persistence
Opening the ACB during recovery from an application failure
Takeover OPEN
Application program recovery with multinode persistence enabled
Response to a node failure
Response to an application failure with MNPS
Opening the ACB during recovery from a node failure
Planned Takeover OPEN
Forced Takeover OPEN
Restoring the sessions pending recovery
Closing an application program
Program initiates closing
Program receives a closedown message
TPEND exit routine is entered
Action for a standard HALT command
Action for HALT NET,QUICK command or for VTAM-initiated HALT
Action for HALT NET,CANCEL command or abnormal termination
Action for a takeover OPEN
Opening and closing an application program as a generic resource
Identifying an application program as a generic resource member
Initiating a session using a generic resource name
Initiating a session using the name of an application that is a member of a generic resource
Closing an application program that is a member of a generic resource
Ownership of affinities between LUs and application programs
Terminating affinities that are application-owned
Terminating VTAM-owned affinities
Establishing and terminating sessions with logical units
Defining LUs
Stages of session establishment
Stages of session termination
Sources of SNA Initiate and Terminate requests
Device-type LU Initiate
Application program LU Initiate
Third party Initiate
Device-type LU Terminate
Application program LU Terminate
Third party Terminate
Macroinstructions related to session establishment and termination
SIMLOGON macroinstruction
Initiating sessions with all LUs in a list
Initiating a session with the first LU in a list
Queuing Initiates
Notification to the session partner of a request for a session
OPNDST macroinstruction
Accepting and establishing a single pending active session
Acquiring sessions
Initiating, accepting, and establishing an active session
Initiating, accepting, and establishing active sessions with all LUs in a list
Initiating, accepting, and establishing an active session with the first LU in a list
Restoring sessions
Restoring sessions pending recovery
Extended recovery facility session requests
BIND request
CLSDST macroinstruction
Scope of CLSDST
CLSDST OPTCD=RELEASE
Sense codes on negative response to CINIT
Session outage notification (SON) codes on UNBIND
CLSDST OPTCD=PASS
CLSDST OPTCD=TERMQ
REQSESS macroinstruction
OPNSEC macroinstruction
BIND response
SESSIONC macroinstruction with CONTROL=BIND
TERMSESS macroinstruction
TERMSESS OPTCD=UNBIND
TERMSESS OPTCD=TERMQ
Exit routines related to session establishment and termination
LOGON exit routine
SCIP exit routine
Receiving a BIND request
Receiving an UNBIND request
NSEXIT exit routine
CLEANUP request
NSPE request
Notify request
LOSTERM exit routine
Summary tables of exit routines
Session outage notification
Queuing a request for a session with an SLU
Control blocks used for session establishment and termination
Request parameter list (RPL)
Node initialization block (NIB)
Application-supplied dial parameter control block (ASDP)
Establishing parameters for sessions
General pattern of agreement on session parameters
Defining and naming a set of session parameters (logon mode and class of service)
How logon mode names and session parameters are used
NIB LOGMODE and BNDAREA operands
Examples of how an application program processes session parameters
Example 1: Using session parameters associated with CINIT
Example 2: Locating the logon mode name in the CINIT RU
Example 3: Building and using session parameters in a BIND area
Example 4: Responding to a negotiable BIND request
Establishing cryptographic sessions
Establishing single-domain cryptographic sessions
Establishing cross-domain cryptographic sessions
How VTAM determines the level of cryptography for a cryptographic session
Restoring sessions pending recovery
Data tracking
BID data
BIS data
FMH-5
MODENAME
Session instance identifier
Session qualifier pair
Restoring sessions
Extended recovery facility (XRF) programming
Communicating with logical units
Who is communicating: The VTAM application program and LUs
What is communicated: Requests and responses
What a request contains
Example of data exchange
What a response contains
Definite, exception, or no response indication
Definite response 1 and 2 indication
Three key elements in a RESPOND operand
How requests and responses are exchanged
SEND, RECEIVE, and SESSIONC macroinstructions
Normal-flow and expedited-flow requests and responses
DFSYN, DFASY, and RESP types of RUs
Controlling the handling of normal-flow responses
Sequence numbers
Controlling flow
The Start Data Traffic (SDT) and Clear requests
The Set and Test Sequence Numbers (STSN) and Request Recovery (RQR) Requests
Data-flow-control requests and indicators
Identifying LUs and sessions
Using VTAM to communicate with LUs
Major alternatives
Synchronous versus asynchronous operations
Synchronous requests
Asynchronous requests
ECBs versus RPL exit routines
Scheduled versus responded output operations
Receiving input from any session versus from a specific session
Continue-any mode versus continue-specific mode
Explicit RECEIVEs and EXLST exit routines
Queued response notification
Handling overlength input data
Large message performance enhancement outbound (LMPEO) option
LMPEO operating considerations
Handling request headers (RH)
LMPEO sequence number handling
Data-stream considerations
Exception conditions
Performance considerations for LMPEO
The buffer-list (BUFFLST) option
BUFFLST operating considerations
Buffer-list LMPEO states
(Begin RU, End RU)=(1,1)
(Begin RU, End RU)=(1,0)
(Begin RU, End RU)=(0,1)
(Begin RU, End RU)=(0,0)
End of buffer list
The user RH (USERRH) option
USERRH operating considerations
Operation for outbound RUs
Operation for inbound RUs
Relationship to POST=RESP
Relationship to NIB PROC=ORDRESP or NORDRESP operand
Handling the sense data included (SDI) indicator
Example of using LMPEO, BUFFLST, and USERRH
Using SNA protocols
Chaining
Request and response modes
Quiescing
Protocols for ensuring orderly communications
Quiesce protocol
Half-duplex protocols
Bracket protocols
Special use of RESPOND=QRESP with bracket protocol
The Chase request
Function management headers
Additional SNA protocol information
Sending and receiving enciphered data requests
Using exit routines
How exit routines work
RPL exit routines
EXLST exit routines
Summary of exit routines
Deciding whether and how to use exit routines
Specifying the DFASY, RESP, and SCIP exit routines in an ACB or NIB
Special requirements for LERAD and SYNAD exit routines
Exit scheduling versus ECB posting
Procedures to follow in writing exit routines
Entry procedures
Cautions, restrictions and techniques
Exit procedures
DFASY exit routine
LERAD exit routine
LOGON exit routine
TSO/VTAM Katakana and double-byte character set (DBCS) support
LOSTERM exit routine
LOSTERM reason codes
NSEXIT exit routine
Network services procedure error or Notify
Cleanup session
RELREQ exit routine
RESP exit routine
RPL exit routine
SCIP exit routine
Clear
Start Data Traffic (SDT)
Request Recovery (RQR)
Set and Test Sequence Numbers (STSN)
BIND
UNBIND
SYNAD exit routine
TPEND exit routine
Setting and testing control blocks and macro global variables
Setting and testing control block values
Using manipulative macroinstructions
GENCB macroinstruction
Example 1
Example 2
Example 3
MODCB macroinstruction
Example 1
Example 2
Example 3
SHOWCB macroinstruction
Example 1
Example 2
Example 3
Example 4
TESTCB macroinstruction
Example
Using INQUIRE OPTCD=TERMS to generate NIBs
Using DSECT-creating assembler instructions and macroinstructions
Defining the DSECTs
Using the DSECTs
ISTGLBAL macroinstruction
Release-level and component-ID macro global variables
Function-list macro global variables
Handling errors and special conditions
OPEN and CLOSE errors and special conditions
Manipulative macroinstruction errors and special conditions
RPL-based macroinstruction errors and special conditions
Coding LERAD and SYNAD exit routines
Handling exception conditions (register 0=04)
Further action by a PLU application program
Further action by an SLU application program
Handling retriable completion (register 0=08)
Handling data integrity damage (register 0=0C)
Handling environment errors (register 0=10)
Handling logic errors (register 0=14 and register 0=18)
Operating system facilities
VTAM macroinstruction differences across operating systems
Assigning operating system authorization
Authorization criteria
Multitasking
Separating data communication activity from other activity
Dividing data communication activity among several tasks
Multiple tasks, using the same ACB
Multiple tasks, each with its own ACB
Using multiple ACBs within one task
Authorized path
Specifying authorized path macroinstructions
Additional coding considerations for authorized path
Simple example of authorized path usage
Authorized asynchronous exit routines
Execution of exit routines
EXLST exit routines other than LERAD and SYNAD
LERAD and SYNAD exit routines
RPL exit routines
Serialization of execution
Task association
Exit routine task association
Macroinstruction task association
SRB requirements
Multiple address spaces
Types of address spaces
ACB address space
Associated address space
Session address space
Rules for coding macroinstructions and exit routines
Address space used for exit routine execution
Cross-memory application program interface (API) support
31-bit addressing
Opening by the Application Program
Specifying macroinstructions
Declarative macroinstructions
ACB macroinstruction
EXLST, NIB, and RPL macroinstructions
ACB-based macroinstructions
RPL-based macroinstructions
CHECK macroinstruction
Executing exit routines
Closing by the Application Program
Error handling
Isolation of errors
Request level isolation
Session level isolation
Task level isolation
Application program (ACB) level isolation
Task termination and address space termination
Functional recovery routines
Application program functional recovery routines
VTAM recovery routine
Programming for the IBM 3270 Information Display System
Types of 3270 terminals
Characteristics of LU type 0 for 3270 terminals
Data stream
Data flow control
Data-flow-control requests
Chaining
Normal-flow Send/Receive mode
Responses
Brackets
Sequence numbering
Transmission control
Exception conditions and sense information
Session parameter
Device characteristics field
Logon message
Logoff
Test request
Summary of differences among LU type 0 3270 terminals
Coding for the communication network management interface
CNM interface
Functions of the application program
Gathering maintenance-related information from a PU
Gathering session data from VTAM and NCP
Gathering performance data from VTAM
Loading a PU
Receiving hardware alerts
Request unit flow
Application program coding requirements for the CNM interface
CNM interface requests and responses
Protocols and procedures
Request unit (RU) formats
Standard CNM headers
Forward request unit
Deliver request unit
Target resource names
Single target names
NMVT (Network Management Vector Transport) considerations
Request unit names
Examples of embedded network services request units
Types of network services request units not embedded
Alias application
Inquiry data
Constant values
Reply data
Requirements for receiving session-awareness and trace data
VTAM definition requirements
Interfaces and interactions
Session-awareness data buffer
Session notification data format
Trace data buffer
Requirements for receiving performance data
Performance monitor definition requirements for initialization
Data collection mechanism
Categorization of data
Automatic data delivery
Resource inactivation
Non-inactivation events
System Management Facility (SMF) intervals
Switching requests
Data collection dynamics
Performance monitor interface termination
Performance data types
Implications of the multiple monitor environment
Request unit formats for the performance monitor interface
Sense codes for the performance monitor CNM RUs
Protocol violations
Process exceptions
Conventions and descriptions of VTAM macroinstructions
How the macroinstructions are described
How the macroinstructions are coded
Name
Operation
Operands
Types of operands
Comments and continuation lines
Operand descriptions
Operand format
Examples
Completion information
Description of the VTAM macroinstructions
ACB—Create an access method control block
CHANGE—Terminate affinity between LU and generic resource application
CHECK—Check request status
CLOSE—Close one or more ACBs
CLSDST—Terminate sessions, application program is the PLU
Network-qualified names with CLSDST
EXECRPL—Execute a request
EXLST—Create an exit list
GENCB—Generate a control block
INQUIRE—Obtain logical unit information or application program status
INTRPRET—Interpret an input sequence
ISTGLBAL—Declare and set macro global variables
MODCB—Modify the contents of control block fields
NIB—Create a node initialization block
NIB fields set by VTAM
OPEN—Open one or more ACBs
OPNDST—Establish sessions (application as PLU) or recover sessions
OPNSEC—Establish a session, application program acts as the SLU
RCVCMD—Receive a message from VTAM
RECEIVE—Receive input on a session
REQSESS—Initiate a session, application program acts as the SLU
RESETSR—Cancel RECEIVE operations and switch a session's CA-CS mode
RPL—Create a request parameter list
RPL fields set by VTAM
RPL fields and RPL-based macroinstructions
SEND—Send output on a session
SENDCMD—Send a VTAM operator command to VTAM
SESSIONC—Send a session-control request or response
Send a Start Data-Traffic request to the SLU
Send a Clear request to the SLU
Send a Request Recovery request to the PLU
Send a Set and Test Sequence Number request to the SLU
Send the PLU a response to a Set and Test Sequence Number (STSN) request
Send the PLU a Request-Rejected response to a BIND request
Send the PLU a response to an SDT request
Send a Switch request initiating the switch from backup to primary session status
SETLOGON—Modify an application program's capability to establish sessions
SHOWCB—Extract the contents of control block fields
Control block fields applicable for SHOWCB
SIMLOGON—Initiate a session, application program acts as the PLU
TERMSESS—Request session termination, application program is SLU
TESTCB—Test the contents of a control block field
Control block fields applicable for TESTCB
Logic of a simple application program
Logic of Sample Program 1
Sample code of a simple application program
What SAMP1 does
How SAMP1 relates to Sample Program 1 (Chapter 14)
Data interface between SAMP1 and LUs
Notes on SAMP1
Mainline program
LOGON exit routine
RESP exit routine
LERAD and SYNAD exit routines
LOSTERM exit routine
SAMP1
Logic of a more complicated application program
Introduction
Organization and flow of Sample Program 2
Logic of the 3600 finance communication system I/O routine
Logic of the 3600 chaining output routine
Routine logic of the 3270 I/O routine
Logic of the RESP exit routine
Logic of the DFASY exit routine of Sample Program 2
Sample code using authorized path
Notes on SAMP3
SAMP3 assembler language code
Summary of control block field usage
ACB
CHANGE
CHECK
CLOSE
CLSDST
EXECRPL
EXLST
GENCB
INQUIRE
INTRPRET
ISTGLBAL
MODCB
NIB
OPEN
OPNDST
OPNSEC
RCVCMD
RECEIVE
REQSESS
RESETSR
RPL
SEND
SENDCMD
SESSIONC
SETLOGON
SHOWCB
SIMLOGON
TERMSESS
TESTCB
Return codes and sense fields for RPL-based macroinstructions
Return code posting
RPL return code (RTNCD,FDB2) combinations
SNA sense fields
System-sense information
Summary of control requests and indicators
Request and response exchanges for typical communication operations
Control block formats and DSECTs
ACB (IFGACB)
ASDP (ISTASDP)
BLENT (ISTBLENT)
Control vector hex 29 (CV29)
EXLST (IFGEXLST)
MTS override (ISTMTS)
NIB (ISTDNIB)
NIB DEVCHAR (ISTDVCHR)
NIB PROC (ISTDPROC)
NRIPL (ISTNRIPL)
Request/response header (ISTRH)
RPL (IFGRPL)
RPL RTNCD-FDB2-FDBK (ISTUSFBC)
Access-method-support vector list (ISTAMSVL)
Resource-information vector list (ISTRIVL)
Application-ACB vector list (ISTVACBV)
Specifying a session parameter
Session parameter fields (BIND image)
Format
Type
Function management profile
Transmission services profile
Transmission services usage field
Request unit size
Pacing count
Logical unit presentation services profile
LU type 0
LU type 1
LU type 2
LU type 3
LU type 4
LU type 6 for LU 6.2
Logical unit presentation services usage field
Profile 0
Media flags
Profile 1
Function management header subset and data stream profile
Function management header subset flags
Data stream subset flags
Media flags
Profiles 2 and 3
Presentation services flags
Presentation space size
Profile 4
Logical unit send capability
Code selection
General characteristics
Profile 6 for LU 6.2
LU level
LU 6.2 flags
LU 6.2 flags
Cryptographic control
Primary logical unit name length
Primary logical unit name
User data length
User data
BIND area format and DSECT
XRF session activation control vector
RPL fields associated with VTAM macroinstructions
Summary of register usage
Return codes for manipulative macroinstructions
Summary of operand specifications
Address
Quantity
Fixed value
Name
Register-indirect value
Indirect value
Forms of the manipulative macroinstruction
Optional and required operands
Optional and required operands for the alternative forms of GENCB
Optional and required operands for the alternative forms of MODCB
Optional and required operands for the alternative forms of SHOWCB
Optional and required operands for the alternative forms of TESTCB
Program operator coding requirements
Defining a program operator
Authorizing a program operator
Method for writing a program operator
VTAM operator commands
Operational characteristics
Messages rerouted to a PPO
Programming requirements
Orderly closing of a program operator
Limiting VTAM messages queued to a program operator
Data exchanged between a program operator and VTAM
Header
Data received from VTAM
Data sent to VTAM
Format and DSECT of the message and command header
POA communication with tuning facility using the MODIFY QUERY COMMAND
List of macroinstructions
Application program migration
Migrating from prior releases of VTAM
COS name and logon mode name
Increase of ACB size
Application program minor node name in BIND
Sequence number dependencies for LU type 0 3270 terminals
Dynamic network access function
Differences between BTAM and VTAM application programs
Migrating from a single-domain to a multiple-domain environment
Use of INQUIRE for a cross-domain resource
Specifying LOGMODE names with OPNDST for a cross-domain resource
Use of INTRPRET for a cross-domain resource
Considerations for a multiple-network environment
Use of INQUIRE for a cross-network resource
Architectural specifications
Accessibility
Bibliography
Index
Index for Communications Server: SNA Programming