Abstract for SNA Programming

Purpose of this information

This manual describes programming concepts and VTAM® macroinstructions. Use it as a guide when designing and coding application programs. This publication covers all macroinstructions except APPCCMD (see the z/OS Communications Server: SNA Programmer's LU 6.2 Reference) and macroinstructions related to the installation of VTAM (see the z/OS Communications Server: SNA Resource Definition Reference).

This document supports z/OS®.e.

Who should read this information

This document is designed to help programmers (such as application or system programmers) write application programs that use VTAM macroinstructions.

How this information is organized

This document contains the following chapters:

VTAM application program concepts provides an overview of a VTAM application program.
VTAM language contains the following:
- Characteristics of the VTAM language
- A summary of the VTAM application program macroinstructions
- Relationships among the VTAM control blocks as well as their relationship to the macroinstructions
- A description of a normal operating system environment for a VTAM application program
Organizing an application program discusses the following:
- General coding guidelines to consider when writing an application program
- Coding guidelines to facilitate migration of application programs
- Whether the application program should be single-thread or multithread
- Whether the application program operation should be synchronous or asynchronous and what posting mechanism should be used
- VTAM and user control block decisions to be made that affect application program organization
Opening and closing an application program describes aspects of the OPEN, CLOSE, and ACB macroinstructions that apply to all application programs.
Establishing and terminating sessions with logical units describes how VTAM establishes and terminates a session between LUs.
Communicating with logical units provides a general description of communication facilities.
Using exit routines discusses how exit routines work, presents some of their advantages and disadvantages, and describes procedures to follow in using them.
Setting and testing control blocks and macro global variables discusses the ways in which the VTAM application program sets and tests control block values.
Handling errors and special conditions discusses how to analyze information for errors and special conditions and what to do, in general, when the error or special condition is identified.
Operating system facilities describes a number of operating-system-dependent facilities to use when writing a VTAM application program.
Programming for the IBM 3270 Information Display System describes VTAM application programming for sessions that use LU type 0 protocols.
Coding for the communication network management interface describes the coding required for an application program to function on the communication network management (CNM) interface.
Conventions and descriptions of VTAM macroinstructions describes the format of the macroinstructions and then presents each macroinstruction in alphabetical order.
Logic of a simple application program shows the logic of a VTAM application program that receives a request for a session with a logical unit (LU), establishes the session, reads input from any session, processes the input, prepares a reply for output, and writes the output on the session.
Sample code of a simple application program contains the assembler language instructions for a VTAM application program, SAMP1.
Logic of a more complicated application program contains a more typical example of a VTAM application program than SAMP1.
Sample code using authorized path contains sample program, SAMP3, which shows an application program using the authorized path facility under the control of both a task control block (TCB) and a service request block (SRB).
Summary of control block field usage serves as a reference for the experienced VTAM application programmer by showing the information for each executable macroinstruction discussed in this document.
Return codes and sense fields for RPL-based macroinstructions provides information about return code posting and explains what the different return code and feedback field values mean. It also provides information about SNA sense fields.
Summary of control requests and indicators contains tables that summarize the SNA control requests and indicators sent and received by VTAM application programs.
Request and response exchanges for typical communication operations contains diagrams that show the sequences in which requests and responses are exchanged to perform typical data communication operations using VTAM.
Control block formats and DSECTs contains file description control block formats and DSECTs.
Specifying a session parameter describes the format of the session parameter as seen by a VTAM application program.
RPL fields associated with VTAM macroinstructions shows fields modified by the SEND and SESSIONC macroinstructions.
Summary of register usage shows what VTAM does with the general-purpose registers before it returns control to the application program at the next sequential instruction.
Return codes for manipulative macroinstructions explains return codes for manipulative macroinstructions.
Summary of operand specifications indicates which manipulative macroinstructions apply for each operand and the types of values that can be coded with each operand.
Forms of the manipulative macroinstruction summarizes the actions of various forms of manipulative macroinstructions.
Program operator coding requirements describes how to write the program operator portion of a VTAM application program using the SENDCMD and RCVCMD macroinstructions.
List of macroinstructions contains macroinstructions provided as programming interfaces by VTAM. Do not use as programming interfaces any VTAM macroinstructions other than those identified in this appendix.
Application program migration describes factors to consider in various migration environments.
"Architectural specifications" lists documents that provide architectural specifications for the SNA protocol.
"Accessibility" describes accessibility features to help users with physical disabilities.
"Notices" contains notices and trademarks used in this document.
"Bibliography" contains descriptions of the documents in the z/OS Communications Server library.

Conventions and terminology that are used in this information

Commands in this information that can be used in both TSO and z/OS UNIX environments use the following conventions:

When describing how to use the command in a TSO environment, the command is presented in uppercase (for example, NETSTAT).
When describing how to use the command in a z/OS UNIX environment, the command is presented in bold lowercase (for example, netstat).
When referring to the command in a general way in text, the command is presented with an initial capital letter (for example, Netstat).

All the exit routines described in this information are installation-wide exit routines. The installation-wide exit routines also called installation-wide exits, exit routines, and exits throughout this information.

The TPF logon manager, although included with VTAM, is an application program; therefore, the logon manager is documented separately from VTAM.

Samples used in this information might not be updated for each release. Evaluate a sample carefully before applying it to your system.

Note: In this information, you might see the following Shared Memory Communications over Remote Direct Memory Access (SMC-R) terminology:

RoCE Express®, which is a generic term representing IBM® 10 GbE RoCE Express, IBM 10 GbE RoCE Express2, and IBM 25 GbE RoCE Express2 feature capabilities. When this term is used in this information, the processing being described applies to both features. If processing is applicable to only one feature, the full terminology, for instance, IBM 10 GbE RoCE Express will be used.
RoCE Express2, which is a generic term representing an IBM RoCE Express2® feature that might operate in either 10 GbE or 25 GbE link speed. When this term is used in this information, the processing being described applies to either link speed. If processing is applicable to only one link speed, the full terminology, for instance, IBM 25 GbE RoCE Express2 will be used.
RDMA network interface card (RNIC), which is used to refer to the IBM® 10 GbE RoCE Express, IBM® 10 GbE RoCE Express2, or IBM 25 GbE RoCE Express2 feature.
Shared RoCE environment, which means that the "RoCE Express" feature can be used concurrently, or shared, by multiple operating system instances. The feature is considered to operate in a shared RoCE environment even if you use it with a single operating system instance.

Clarification of notes

Information traditionally qualified as Notes is further qualified as follows:

Attention: Indicate the possibility of damage
Guideline: Customary way to perform a procedure
Note: Supplemental detail
Rule: Something you must do; limitations on your actions
Restriction: Indicates certain conditions are not supported; limitations on a product or facility
Requirement: Dependencies, prerequisites
Result: Indicates the outcome
Tip: Offers shortcuts or alternative ways of performing an action; a hint

How to read a syntax diagram

This section describes how to read the syntax diagrams used in this book.

Read the diagrams from left-to-right, top-to-bottom, following the main path line. Each diagram begins on the left with double arrowheads (►►) and ends on the right with two arrowheads facing each other (►◄).
If a diagram is longer than one line, the first line ends with a single arrowhead (►) and the second line begins with a single arrowhead.
Required operands and values appear on the main path line.

You must code required operands and values.

If there is more than one mutually exclusive required operand or value to choose from, they are stacked vertically in alphanumeric order.
Optional operands and values appear below the main path line.

You can choose not to code optional operands and values.

If there is more than one mutually exclusive optional operand or value to choose from, they are stacked vertically in alphanumeric order below the main path line.
An arrow returning to the left above an operand or value on the main path line means that the operand or value can be repeated. The comma means that each operand or value must be separated from the next by a comma.
An arrow returning to the left above a group of operands or values means more than one can be selected, or a single one can be repeated.
A word in all uppercase is an operand or value you must spell exactly as shown. In this example, you must code OPERAND.
Note: VTAM and IP commands are not case sensitive. You can code them in uppercase or lowercase. If the operand is shown in both uppercase and lowercase, the uppercase portion is the abbreviation (for example, OPERand).

If an operand or value can be abbreviated, the abbreviation is described in the text associated with the syntax diagram.
If a diagram shows a character that is not alphanumeric (such as parentheses, periods, commas, and equal signs), you must code the character as part of the syntax. In this example, you must code OPERAND=(001,0.001).
If a diagram shows a blank space, you must code the blank space as part of the syntax. In this example, you must code OPERAND=(001 FIXED).
Default operands and values appear above the main path line. VTAM uses the default if you omit the operand entirely.
A word in all lowercase italics is a variable. Where you see a variable in the syntax, you must replace it with one of its allowable names or values, as defined in the text.
References to syntax notes appear as numbers enclosed in parentheses above the line. Do not code the parentheses or the number.
Notes:
- ¹ An example of a syntax note.
Some diagrams contain syntax fragments, which serve to break up diagrams that are too long, too complex, or too repetitious. Syntax fragment names are in mixed case and are shown in the diagram and in the heading of the fragment. The fragment is placed below the main diagram.

Syntax Fragment