z/OS TSO/E Programming Services
Previous topic |
Next topic
|
Contents
|
Contact z/OS
|
Library
|
PDF
Contents (exploded view)
z/OS TSO/E Programming Services
SA32-0973-00
Abstract for TSO/E Programming Services
z/OS Version 2 Release 1 summary of changes
Introduction
Programming using TSO/E
Writing CLISTs
Writing REXX Execs
Writing servers
Writing Command Processors
Overview of TSO/E programming services
Invoking TSO/E service routines
Establishing a TSO/E environment outside of the TSO/E TMP and service routines
Checking the syntax of subcommand names
Checking the syntax of command and subcommand operands
Communicating with the terminal user
Controlling terminal functions and attributes
Processing terminal I/O
Handling attention interruptions
Processing data sets
Obtaining a list of data set names
Ensuring that data sets contain sufficient space
Allocating, concatenating and freeing data sets
Retrieving information from the system catalog
Constructing a fully-qualified data set name
Changing alternative library environments
Analyzing return codes
Searching system lists
Invoking commands, CLISTs, REXX execs and programs
Accessing CLIST and REXX variables
Retrieving information from the names directory
Displaying printers for selection by the user
Invoking an Information Center Facility application
Retrieving system messages issued during a console session
Coding the macro instructions
Considerations for using TSO/E services
Determining the version and release of TSO/E installed
Programming considerations for MVS/ESA SP
General interface considerations
AR mode
Primary mode
AMODE=24, RMODE=24
AMODE=ANY, RMODE=24
AMODE=31
Interface considerations for the TSO/E service routines
Invoking the TSO/E service routines
Summary of macro interfaces
Interfacing with the TSO/E service routines
The Command Processor parameter list
Services that access data in the CPPL
Using the TSO/E Environment Service IKJTSOEV
Overview of the TSO/E Environment Service
When you should use the TSO/E Environment Service
Function of the TSO/E Environment Service
TSO/E environment initialization - inside IKJTSOEV
Capabilities available after initialization
Job step termination
Restrictions and limitations on the use of TSO/E services
Task structure limitations
TCB key limitations
Background mode limitations
Multi-trans transaction program limitations
Summary of TSO/E services available under IKJTSOEV
Syntax and parameter descriptions
Invoking the TSO/E Environment Service
Requirements and restrictions for invoking the TSO/E Environment Service
Addressability requirements
Resource allocation requirements
REXX ADDRESS TSO support requirements
Return and reason codes from the TSO/E Environment Service
Examples using the TSO/E Environment Service
COBOL
Assembler
JCL for COBOL and assembler program invocation
Invoking TSO/E service routines with CALLTSSR
When to use the CALLTSSR macro instruction
Syntax and operands
Example using TSO/E service routines with CALLTSSR
Verifying subcommand names with IKJSCAN
Functions performed by the Command Scan Service Routine
Syntax requirements for command and subcommand names
Invoking the Command Scan Service Routine (IKJSCAN)
The command scan parameter list
Passing flags to the Command Scan Service Routine
The command scan output area
Output from the Command Scan Service Routine
Return codes from the Command Scan Service Routine
Example using the Command Scan Service Routine
Verifying command and subcommand operands with parse
Overview of the Parse Service Routine (IKJPARS)
The parse macro instructions
Character types accepted by the Parse Service Routine
Treatment of comment character /* by the Parse Service Routine
Acceptance of double-byte character set data
Services provided by the Parse Service Routine
Prompting the user for missing or required operands
How parse processes responses
Issuing error messages when parse does not complete successfully
Issuing second-level messages
Using the prompt mode HELP function
Passing control to validity checking routines
Passing control to verify exit routines
Translation to uppercase
Insertion of default values
Insertion of keywords
What you need to do to use the Parse Service Routine
Defining command operand syntax
Positional operands
Delimiter-dependent operands
Positional operands not dependent on delimiters
Entering positional operands as lists of ranges
Keyword operands
Subfields associated with keyword operands
Using the parse macro instructions to define command syntax
Using IKJPARM to begin the PCL and the PDL
The parameter control entry built by IKJPARM
Using IKJPOSIT to describe a delimiter-dependent positional operand
The parameter control entry built by IKJPOSIT
Using IKJTERM to describe a delimiter-dependent positional operand
The parameter control entry built by IKJTERM
Using IKJOPER to describe a delimiter-dependent positional operand
The parameter control entry built by IKJOPER
Using IKJRSVWD to describe a delimiter-dependent positional parameter
The parameter control entry built by IKJRSVWD
Using IKJIDENT to describe a non-delimiter-dependent positional operand
The parameter control entry built by IKJIDENT
Using IKJKEYWD to describe a keyword operand
The parameter control entry built by IKJKEYWD
Using IKJNAME to list keyword or reserved word operand names
Defining keyword operand names
Defining reserved word operand names
The parameter control entry built by IKJNAME
Using IKJSUBF to describe a keyword subfield
The parameter control entry built by IKJSUBF
Using IKJUNFLD to describe unidentified keyword operands
The parameter control entry built by IKJUNFLD
Using IKJENDP to end the parameter control list
The parameter control entry built by IKJENDP
Using IKJRLSA to release virtual storage allocated by parse
Examples using the parse macro instructions
Example 1: Describing a PROCESS command syntax
Example 2: Describing an EDIT command syntax
Example 3: Describing an AT command syntax
Example 4: Describing a LIST command syntax
Example 5: Describing a WHEN command syntax
Using validity checking routines
Passing control to validity checking routines
The validity check parameter list
Return codes from validity checking routines
Using verify exit routines
Passing control to verify exit routines
The verify exit parameter list
The parse parameter element
Return codes from verify exit routines
Passing control to the Parse Service Routine
The parse parameter list
Checking return codes from the Parse Service Routine
Examining the PDL returned by the Parse Service Routine
The PDL header
PDEs created for positional operands described by IKJPOSIT
SPACE, DELIMITER
STRING, PSTRING, and QSTRING
VALUE
DSNAME, DSTHING
JOBNAME
ADDRESS
Expression value
USERID
UID2PSWD
PDEs created for positional operands described by IKJTERM
CONSTANT
STATEMENT NUMBER
VARIABLE
The PDE created for expression operands described by IKJOPER
The PDE created for reserved word operands described by IKJRSVWD
The PDE created for positional operands described by IKJIDENT
The PDE created for keyword operands described by IKJKEYWD
The PDE created for keyword operands described by IKJUNFLD
How the list and range options affect PDE formats
LIST
RANGE
How combining the LIST and RANGE options affects PDE formats
Examples using the Parse Service Routine
Example 1: Describing a PROCESS command syntax
Example 2: Describing an EDIT command syntax
Example 3: Describing an AT command syntax
Example 4: Describing a LIST command syntax
Example 5: Describing a WHEN command syntax
Using the terminal control macro instructions
Functions of the terminal control macro instructions
GTDEVSIZ - Get Device Size
GTSIZE - Get Terminal Line Size
GTTERM - Get Terminal Attributes
RTAUTOPT - Restart Automatic Line Numbering or Character Prompting
SPAUTOPT - Stop Automatic Line Numbering or Character Prompting
STAUTOCP - Start Automatic Character Prompting
STAUTOLN - Start Automatic Line Numbering
STFSMODE - Set Full-Screen Mode
STLINENO - Set Line Number
STSIZE - Set Terminal Line Size
STTMPMD - Set Terminal Display Manager Options
TCLEARQ - Clear Buffers
STATTN - Set Attention Simulation
STBREAK - Set Break
STCC - Specify Terminal Control Characters
STCLEAR - Set Display Clear Character String
STCOM - Set Inter-Terminal Communication
STTIMEOU - Set Time Out Feature
STTRAN - Set Character Translation
Using BSAM or QSAM for terminal I/O
Overview of the BSAM and QSAM macro instructions
The SAM Terminal Routines
GET
PUT and PUTX
READ
WRITE
CHECK
Record Formats, Buffering Techniques, and Processing Modes
Specifying Terminal Line Size
End-of-File (EOF) for Input Processing
Modifying DD Statements for Batch or TSO/E Processing
Using the TSO/E I/O service routines for terminal I/O
Functions of the I/O Service Routines
Passing Control to the I/O Service Routines
Addressing Mode Considerations
Considerations for Using I/O Service Routines by a Multitasking Application
The Input/Output Parameter List
Using the I/O Service Routine macro instructions
Using STACK to Change the Source of Input
STACK Macro Effects on the REXX Data Stack
The List Form of the STACK macro instruction
The Execute Form of the STACK macro instruction
The Sources of Input
Terminal
In-Storage List
Building the STACK Parameter Block (STPB)
Building the List Source Descriptor (LSD)
Return Codes from STACK
Examples Using STACK
Example 1
Example 2
Example 3
Using GETLINE to Get a Line of Input
The List Form of the GETLINE macro instruction
The Execute Form of the GETLINE macro instruction
Sources of Input
The REXX Data Stack
The Input Stack
Terminal
In-Storage List
End of Data Processing
Building the GETLINE Parameter Block
Input Line Format - The Input Buffer
Return Codes from GETLINE
Examples Using GETLINE
Using PUTLINE to Put a Line Out to the Terminal
The List Form of the PUTLINE macro instruction
The Execute Form of the PUTLINE macro instruction
Building the PUTLINE Parameter Block
Types and Formats of Output Lines
Data Lines
Message Lines
Passing the Message Lines to PUTLINE
PUTLINE Message Line Processing
Stripping Message Identifiers
Using the PUTLINE Text Insertion Function
Offset Values
Using the Format Only Function
Building a Second Level Informational Chain
Displaying Translated Message Text
Return Codes from PUTLINE
Using PUTGET to Put a Message Out to the Terminal and Obtain a Line of Input in Response
The List Form of the PUTGET macro instruction
The Execute Form of the PUTGET macro instruction
Building the PUTGET Parameter Block (PGPB)
Types and Formats of the Output Line
Single-Level Messages
Multilevel Messages
Passing the Message Lines to PUTGET
PUTGET Processing
Mode Message Processing
Is an Output Line Present?
What Is the Input Source?
Mode Message Response Processing
Pause Processing
Prompt Message Processing
Input Line Format - The Input Buffer
Return Codes from PUTGET
An Example Using PUTGET
Using the TGET/TPUT/TPG macro instructions for terminal I/O
Overview of the TGET, TPUT and TPG macro instructions
Using the TPUT macro instruction to Write a Line to the Terminal
Return Codes from TPUT
Using the TPG macro instruction to Write a Line Causing Immediate Response
Return Codes from TPG
Using the TGET macro instruction to Get a Line from the Terminal
Return Codes from TGET
Parameter Formats for TGET, TPUT, and TPG
Register Form of TGET and TPUT
Execute, Standard and List Forms of TPUT
Execute and List Forms of TPG
Standard, List and Execute Forms of TGET
Examples Using the TGET and TPUT macro instructions
Example 1: Using the Default Values for TPUT and TGET
Example 2: Using TPUT with Buffer Address and Buffer Length in Registers
Example 3: Using the Register Format of TGET
Using the TSO/E message handling routine IKJEFF02
Overview of Message Handling
TSO/E Message Issuer Routine (IKJEFF02)
Passing Control to the TSO/E Message Issuer Routine
The Input Parameter List
Standard Format of the Input Parameter List
Extended Format of Input Parameter List
Using IKJTSMSG to Describe Message Text and Insert Locations
Return Codes from the TSO/E Message Issuer Routine
Example Using IKJTSMSG
Using the STAX service routine to handle attention interrupts
The STAX macro instruction
Return Codes from the STAX Service Routine
Example Using the STAX macro instruction
Using the CLIST attention facility
Overview of the CLIST Attention Facility
Invoking the CLIST Attention Facility
Establishing the Exit that Invokes IKJCAF
Passing Parameters to IKJCAF
Passing Control to IKJCAF
Returning from the CLIST Attention Facility
Obtaining a List of data set names
Operation of ICQGCL00
Invoking ICQGCL00
Output Table Variables
Return Codes from ICQGCL00
Example Using ICQGCL00
Using the space management CLIST ICQSPC00
Functions of ICQSPC00
Applications
Considerations for Using ICQSPC00
Invoking ICQSPC00
Return and Reason Codes from ICQSPC00
Examples Using ICQSPC00
Example 1: The SPACE MANAGER CLIST
Example 2: The SPACE ENLARGER CLIST
Using IKJADTAB to change alternative library environments
Functions of IKJADTAB
Passing Control to IKJADTAB
The IKJADTAB Parameter List
Output from IKJADTAB
Return Codes from IKJADTAB
Example Using IKJADTAB
Using the dynamic allocation interface routine DAIR
Functions of the Dynamic Allocation Interface Routine
Passing Control to DAIR
The DAIR Parameter List (DAPL)
The DAIR Parameter Block (DAPB)
Determining if Ddname or Dsname is Allocated (Entry Code X’00’)
Determining if Dsname is Allocated or is in the System Catalog (Entry Code X’04’)
Allocating a Data Set by Dsname (Entry Code X’08’)
Concatenating the Specified Ddnames (Entry Code X’0C’)
Deconcatenating the Indicated Ddname (Entry Code X’10’)
Returning Qualifiers for the Specified Dsname (Entry Code X’14’)
Freeing the Specified Data Set (Entry Code X’18’)
Allocating the Specified Ddname to the Terminal (Entry Code X’1C’)
Allocating a Data Set by Ddname (Entry Code X’24’)
Performing a List of DAIR Operations (Entry Code X’28’)
Marking Data Sets as Not in Use (Entry Code X’2C’)
Allocating a SYSOUT Data Set to the Message Class (Entry Code X’30’)
Associating DCB Parameters with a Specified Name (Entry Code X’34’)
The DAIR Attribute Control Block (DAIRACB)
Return Codes from DAIR
Reason Codes from Dynamic Allocation
Using IKJEHCIR to retrieve system catalog information
Functions of the Catalog Information Routine
Passing Control to the Catalog Information Routine
The Catalog Information Routine Parameter List (CIRPARM)
Output from the Catalog Information Routine
Return Codes from IKJEHCIR
Return Codes from LOCATE
Constructing a fully-qualified data set name with IKJEHDEF
Functions of the Default Service Routine
Passing Control to the Default Service Routine
The Default Parameter List (DFPL)
The Default Parameter Block (DFPB)
Output from the Default Service Routine
Return Codes from IKJEHDEF
Using the DAIRFAIL routine IKJEFF18
Functions of DAIRFAIL
Passing Control to DAIRFAIL
The Parameter List
Return Codes from DAIRFAIL
Analyzing error conditions with GNRLFAIL/VSAMFAIL
Functions of GNRLFAIL/VSAMFAIL
Passing Control to GNRLFAIL/VSAMFAIL
The Parameter List
Return Codes from GNRLFAIL/VSAMFAIL
Using the table look-up service IKJTBLS
Functions of IKJTBLS
Passing Control to IKJTBLS
The IKJTBLS Parameter List
Return Codes from IKJTBLS
Example Using IKJTBLS
Using the TSO/E Service Facility IKJEFTSR
Overview of the TSO/E Service Facility
The TSO/E Service Facility Routines
Program Authorization and Isolation
Using the Command/Program Invocation Platform
Creating the Platform with IKJEFTSI
Executing Commands or Programs on the Platform with IKJEFTSR
Terminating the Platform with IKJEFTST
TSO/E Service Facility Initialization Routine IKJEFTSI
Passing Control to IKJEFTSI
IKJEFTSI Parameter List
Output from IKJEFTSI
Return Codes from IKJEFTSI
TSO/E Service Facility Routine IKJEFTSR
Passing Control to IKJEFTSR
IKJEFTSR Parameter List
Output from IKJEFTSR
Return Codes from IKJEFTSR
Reason Codes from IKJEFTSR
Considerations on Attention Interruptions with IKJEFTSR
TSO/E Service Facility Termination Routine IKJEFTST
Passing Control to IKJEFTST
IKJEFTST Parameter List
Output from IKJEFTST
Return Codes from IKJEFTST
Application Program Interface to IKJEFTSR
Call Invocations Using TSOLNK
PL/I
COBOL
FORTRAN
PASCAL
Examples of Invoking the TSO/E Service Facility
Assembler Program Using IKJEFTSI
Assembler Program Using IKJEFTSR to Invoke a Command
Assembler Program Using IKJEFTST
Assembler Program Using IKJEFTSI, IKJEFTSR, IKJEFTST to Invoke a Command
FORTRAN Program Using TSOLNK to Invoke a Command (FORTRAN G1)
FORTRAN Program Using TSOLNK to Invoke a Command (VS FORTRAN)
COBOL Program Using TSOLNK to Invoke a Command
Assembler Program Using IKJEFTSR to Invoke a Program
PL/I Program Using TSOLNK to Invoke a Program
PASCAL Program Using TSOLNK to Invoke a Program
COBOL Program Using TSOLNK to Invoke a Program
PL/I Program Using TSOLNK to Invoke a CLIST
PL/I Program Calling a CLIST
PASCAL Program Using TSOLNK to Invoke a CLIST
Assembler Program Using IKJEFTSR to Invoke a REXX Exec
Using the variable access routine IKJCT441
Functions Provided by IKJCT441
Considerations for Accessing REXX Variables
Passing Control to IKJCT441
The IKJCT441 Parameter List
Updating or Creating a Variable Value (TSVEUPDT)
Output from IKJCT441 on Entry Code TSVEUPDT
Return Codes from IKJCT441 on Entry Code TSVEUPDT
Returning the Value of a Variable (TSVERETR) - Create
Output from IKJCT441 on Entry Code TSVERETR
Return Codes from IKJCT441 on Entry Code TSVERETR
Returning the Value of a Variable (TSVNOIMP) - No Create
Output from IKJCT441 on Entry Code TSVNOIMP
Return Codes from IKJCT441 on Entry Code TSVNOIMP
Returning all Active Variables and their Values (TSVELOC)
Output from IKJCT441 on Entry Code TSVELOC
Return Codes From IKJCT441 on Entry Code TSVELOC
Examples Using IKJCT441
Example 1: Update or Create a Variable Value
Example 2: Return a Variable Value - Create If Required
Example 3: Return Variable Value - Do Not Create
Example 4: Return All Active Variables and Their Values
Example 5: Update or Create a List of Variables
Accessing the Information Center Facility names directory
Operation of ICQCAL00
Search Input
Search Output
Applications
Invoking ICQCAL00
Input Table Variables
Return Codes from ICQCAL00
Example Using ICQCAL00
Using the printer support CLISTs
Overview of Using the Printer Support CLISTs
Printer Selection CLIST, ICQCPC00
Syntax and Parameters
Return Codes from ICQCPC00
Variables
Retrieving the Variable Data
Print Definition Variables
Naming Convention for Printer Support Variables
Font Definition Variables
Additional Variables
Print CLIST, ICQCPC10
Functions
Applications
ICQCPC10 as the Print Function of a Printer Definition
ICQCPC10 as Part of the Calling Application
Considerations
Syntax and Parameters
Return Codes from ICQCPC10
Print CLIST, ICQCPC15
Functions
Applications
ICQCPC15 as the Print Function of a Printer Definition
ICQCPC15 as Part of the Calling Application
Considerations
Syntax and Parameters
Return Codes from ICQCPC15
Examples Using Printer CLISTs
Example 1: The Printer List CLIST
Example 2: The Print Function CLIST
Invoking an Information Center Facility application
Operation of ICQAMLI0
Invoking ICQAMLI0
Output Table Variables
Return Codes from ICQAMLI0
Reason Codes from ICQAMLI0
Example Using ICQAMLI0
Using the GETMSG service
Functions of GETMSG
Considerations for Using GETMSG
Multiple Applications
Invoking GETMSG
GETMSG Parameters
Output from GETMSG
Return Codes from GETMSG
Displaying the Retrieved Message
Example Using GETMSG
Using the Unauthorized Resource Processor Service IKJURPS
Overview of the TSO/E Unauthorized Resource Processor Service
Application Routine Versus the unauthorized resource processor
Passing Control to IKJURPS
The IKJURPS Parameter List
Invoking the IKJURPS Service
Understanding the Environment in which IKJURPS Operates
Interpreting the Return Information from the IKJURPS Service
Receiving Control in an unauthorized resource processor
Process the Application's Resources
Provide Return Information to the IKJEFT01 TMP Unauthorized Control Layer
The unauthorized resource processor Parameter List
Installing Resource Processors
Environment
Sample IKJURPS Invocation and unauthorized resource processor
Limits for TSO/E service routines
Copyright IBM Corporation 1990, 2014