System SAMPLIB member DFMQTSO, for example, SYS1.SAMPLIB(DFMQTSO)
shown in Figure 1, shows how a DFM
DataAgent can be written in assembler language to invoke TSO. The
DFMQTSO routine links to the IKJTSOEV function.
Figure 1. DFM DataAgent Sample Routine (TSO) Part 1 of
7 TITLE 'DFMQTSO - DFM DataAgent TSO Sample'
*/********************************************************************
*/*PROPRIETARY V3 STATEMENT *
*/*LICENSED MATERIALS - PROPERTY OF IBM *
*/*5695-DF1 *
*/*(C) COPYRIGHT 1997 IBM CORP. *
*/*END PROPRIETARY V3 STATEMENT *
*/********************************************************************
*/********************************************************************
*/* *
*/* $MOD(DFMQTSO) COMP(5695-DF120) *
*/* *
*/* MODULE NAME: DFMQTSO (Quick TSO-Input in PARM) *
*/* *
*/* DESCRIPTION: DFM DataAgent Sample Routine (TSO) *
*/* *
*/* STATUS: Version 1 Release 4.0 (DFSMS) *
*/* *
*/* COPYRIGHT: See copyright statement on previous page *
*/* *
*/* FUNCTION: This module illustrates how a DFM DataAgent can *
*/* be written in assembler language to invoke TSO. *
*/* *
*/* SdU provides a sample application, DFMACALL, that can be *
*/* to invoke this sample. Refer to it for details. *
*/* *
*/* Refer to 'TSO Extensions for MVS: Programming Services' for *
*/* information about using the TSO environment service used in *
*/* this example. *
*/* *
*/* PROCESSING: *
*/* *
*/* LOGIC: *
*/* Refer to block comments in the code. *
*/* *
*/* ERROR PROCESSING: *
*/* Issue a WTO and then return with register 15 set to a *
*/* non-zero value and with the reason code set to a unique *
*/* value. *
*/* *
Figure 2. DFM DataAgent Sample Routine (TSO) Part 2 of
7*/* NOTES: *
*/* *
*/* PATCH SPACE: None *
*/* XAX CONSIDERATIONS: AMODE(31) RMODE(ANY) ENV(PRI) *
*/* DEPENDENCIES: None *
*/* RESTRICTIONS: None *
*/* REGISTER CONVENTIONS: Standard *
*/* SERIALIZATION: No serialization techniques are used by this *
*/* module. *
*/* *
*/* MODULE TYPE: Procedure *
*/* PROCESSOR: z/OS Assembler *
*/* ATTRIBUTES: *
*/* TYPE: Not reentrant *
*/* PRIMARY ASID: Caller's ASID *
*/* SECONDARY ASID: Same as primary *
*/* HOME ASID: Same as primary *
*/* MODE: Task *
*/* KEY: 8 (Current task TCBPKF=jobstep task TCBPKF)*
*/* STATE: Problem program, non-APF-authorized *
*/* LOCATION: Link library *
*/* *
*/* ENTRY POINT: DFMQTSO *
*/* *
*/* PURPOSE: Show that a DataAgent routine can invoke TSO. *
*/* LINKAGE: Called by Distributed FileManager. *
*/* INPUT: Refer to the DFM Guide and Reference for a general *
*/* description of the parameter list format. Refer to *
*/* DFMACALL documentation for command line invocation from *
*/* SdU. *
*/* *
*/* MESSAGES: Refer to WTO statements. *
*/* *
*/* EXIT NORMAL: *
*/* *
*/* RETURN CODE: Register 15 = 0 *
*/* REASON CODE: Not applicable *
*/* MESSAGE ID: None: *
*/* *
*/* EXIT ERRORS: *
*/* *
*/* RETURN CODE: Register 15 = non-zero *
*/* REASON CODE: Unique values set in the extended parameter *
*/* list *
*/* MESSAGE ID: See WTO statements. *
*/* *
*/* EXTERNAL REFERENCES: None *
*/* *
*/* CHANGE ACTIVITY: *
*/* $L0=DFSMS14,HDZ11D0,960628,SJPLMMR: DFM DataAgent initial code *
*/********************************************************************
Figure 3. DFM DataAgent Sample Routine (TSO) Part 3 of
7DFMQTSO CSECT
DFMQTSO AMODE 31
DFMQTSO RMODE ANY
STM R14,R12,12(R13)
BALR R12,0
USING *,R12
ST R13,SAVEAREA+4
LA R11,SAVEAREA
ST R11,8(,R13)
LA R13,SAVEAREA
LR R3,R1 Save original parameter pointers
SR R15,R15 Clear error code
USING INPARMS,R3 Address of MVS parameter list
L R4,STDPARMP Point to DFM DataAgent parameters
USING STDPARMS,R4 Base of DFM DataAgent parameters
L R5,EXTPARMP Point to DFM DataAgent parameters
USING EXTPARMS,R5 Base of DFM DataAgent parameters
*------------------------------------------------------------------*
* Called for a file or directory. See whether declaration *
* is being created or deleted. *
*------------------------------------------------------------------*
CLC EXTCMDCP,DCLFIL Is file being declared?
BE DODCLFIL Yes, process DCLFIL.
CLC EXTCMDCP,DELDCL Is file declaration being deleted?
BE DODELDCL Yes, process DELDCL.
*------------------------------------------------------------------*
* Unknown command type *
*------------------------------------------------------------------*
WTO 'DFMQTSO: Unknown command code.'
LA R15,16 Exit without trying to set reason code
B EXIT
*
*------------------------------------------------------------------*
* DCLFIL Processing (DCLFIL, or Declare File, is a DDM, *
* Distributed Data Management, command issued when a remote *
* file or directory is about to be opened) *
*------------------------------------------------------------------*
DODCLFIL EQU *
WTO 'DFMQTSO: Declaring a file.'
***********************************************************************
* CALTSOEV - CALL THE TSO/E ENVIRONMENT SERVICE TO ESTABLISH A TSO/E
* ENVIRONMENT IN THIS PROGRAM'S ADDRESS SPACE.
* PARM1 IS RESERVED
* PARM2 IS A FULLWORD THAT WILL CONTAIN THE RETURN CODE FROM IKJTSOEV
* PARM3 IS A FULLWORD THAT WILL CONTAIN THE REASON CODE ON RETURN
* FROM IKJTSOEV.
* PARM4 IS A FULLWORD THAT WILL CONTAIN THE ABEND CODE, IF AN ABEND
* OCCURS DURING TSO/E ENVIRONMENT SERVICE PROCESSING.
* PARM5 IS A FULLWORD THAT WILL CONTAIN THE ADDRESS OF THE CPPL.
***********************************************************************
CALTSOEV DS 0H
XC PARM1,PARM1
LINK EP=IKJTSOEV,ERRET=LE,PARAM=(PARM1,PARM2,PARM3,PARM4,PARM*
5),VL=1
Figure 4. DFM DataAgent Sample Routine (TSO) Part 4 of
7***********************************************************************
* CHKEVRC - CHECK THE RETURN CODE FROM IKJTSOEV
***********************************************************************
CHKEVRC DS 0H
L R2,PARM2
LTR R2,R2
BNZ BADEVRC
***********************************************************************
* TSO Environment established–process the input file.
***********************************************************************
***********************************************************************
* CALLTSR - Call IKJEFTSR to process the input file or the parameter
* list–depending on whether a parameter list is present.
* The output from the commands will go to the SYSTSPRT file.
***********************************************************************
CALLTSR DS 0H
LH R2,STDPARML Get length of input parameters
LTR R2,R2 If zero then use the input file
BZ USEINFIL
ST R2,BUFLEN Set buffer length
BCTR R2,0
EX R2,COPYCMD Copy command to parameter area
L R15,CVTPTR
L R15,CVTTVT(,R15)
L R15,TSVTASF-TSVT(,R15)
CALL (15),(FLAGS,CMDBUFF,BUFLEN,RETCODE,RSNCODE,ABNDCODE),VL
***********************************************************************
* DOALL - At this point, process the return values from
* IKJEFTSR and the invoked functions.
***********************************************************************
DOALL DS 0H
LTR R15,R15
BZ EXIT Exit if no error
C R15,=F'4' Did CLIST or REXX exec fail?
BNE SAVERC No, just ensure RC is saved
MVC RSNCODE,RETCODE Use CLIST/REXX RC as reason code
SAVERC ST R15,RETCODE Ensure a retcode is set
WTO 'DFMQTSO: IKJEFTSR failed.'
L R15,RETCODE Set return code
MVC EXTRSNC1,RSNCODE Set reason code 1
MVC EXTRSNC2,ABNDCODE Set reason code 2 to ABEND code
B EXIT
COPYCMD MVC CMDBUFF(0),STDPARMC
*
Figure 5. DFM DataAgent Sample Routine (TSO) Part 5 of
7*------------------------------------------------------------------*
* SYSTSIN Processing *
*------------------------------------------------------------------*
USEINFIL EQU *
WTO 'DFMQTSO: SYSTSIN input not supported. Use DFMXTSO.'
LA R15,8
B EXIT
*
*------------------------------------------------------------------*
* DELDCL Processing (DELDCL, or Delete Declaration, is a DDM, *
* Distributed Data Management, command issued after a remote *
* file or directory has been closed) *
*------------------------------------------------------------------*
DODELDCL EQU *
WTO 'DFMQTSO: Deleting file declaration.'
SR R15,R15 Exit with no error
B EXIT Exit with return code from Sort
***********************************************************************
* LE - Branch here if LINK failed. The ABEND code will be in
* register 1 but there will be no reason code. Set the
* return code to 8 and use the ABEND code as the reason code.
***********************************************************************
*
LE DS 0H
ST R1,EXTRSNC1 Save the ABEND code
WTO 'DFMQTSO: LINK to IKJTSOEV failed.'
LA R15,8
B EXIT
*
***********************************************************************
* BADEVRC - Branch here if IKJTSOEV returned a non-zero return code.
* If the program branches here, it will exit with an error.
* In the DFM diagnostics, the error data will be as follows:
* RETURN CODE - THE RETURN CODE FROM IKJTSOEV
* REASON CODE 1 - THE REASON CODE FROM IKJTSOEV
* REASON CODE 2 - THE ABEND CODE FROM IKJTSOEV
***********************************************************************
BADEVRC DS 0H
WTO 'DFMQTSO: IKJTSOEV error occurred.'
L R15,PARM2
MVC EXTRSNC1,PARM3
MVC EXTRSNC2,PARM4
B EXIT
Figure 6. DFM DataAgent Sample Routine (TSO) Part 6 of
7***********************************************************************
* EXIT - RETURN TO CALLING PROGRAM
***********************************************************************
EXIT DS 0H
L R13,4(,R13)
RETURN (14,12),RC=(15) RESTORE REGS,FLAG SAVEAREA,SET RC
*
* REGISTER EQUATES
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
* PARAMETERS USED TO INVOKE THE TSO/E ENVIRONMENT SERVICE
PARM1 DS F RESERVED FIELD
PARM2 DS F RETURN CODE FIELD
PARM3 DS F REASON CODE FIELD
PARM4 DS F FUNCTION ABEND CODE
PARM5 DS F CPPL ADDRESS
* PARAMETERS USED TO INVOKE THE TSO SERVICE FACILITY
FLAGS DS 0F FULLWORD OF FLAGS
RESFLAGS DC H'0001' ESTABLISH UNAUTHORIZED ENVIRONMENT
ABFLAGS DC X'01' PRODUCE A DUMP IF FUNCTION ABENDS
FNCFLAGS DC X'01' INVOKE TSO/E CMD, REXX EXEC, CLIST
CMDBUFF DS 256C COMMAND BUFFER
BUFLEN DS F LENGTH OF COMMAND BUFFER
RETCODE DS F FUNCTION RETURN CODE
RSNCODE DS F FUNCTION REASON CODE
ABNDCODE DS F FUNCTION ABEND CODE
CVTPTR EQU 16 THESE 2 PARMS ARE USED TO GET
CVTTVT EQU X'9C' ADDR OF THE TSO SERVICE FACILITY
* SAVEAREA AND OTHER PROGRAM STORAGE
SAVEAREA DS 18F
* TSVT MAPPING MACRO (USED TO GET THE ADDRESS OF TSO SERVICE FACILITY)
IKJTSVT
DFMQTSO CSECT
LTORG
*
*------------------------------------------------------------------*
* Define input parameters. *
*------------------------------------------------------------------*
* The standard format MVS parameter list is a halfword length *
* field followed by a parameter list. In this case the *
* parameter list is a TSO command. *
*------------------------------------------------------------------*
*
Figure 7. DFM DataAgent Sample Routine (TSO) Part 7 of
7*------------------------------------------------------------------*
* Constants for use with the DFM DataAgent extended parameters. *
*------------------------------------------------------------------*
DCLFIL DC X'102C' Declare file command code point
DELDCL DC X'102D' Delete declare file command code point
DRCNAM DC X'1165' Directory is being declared
FILNAM DC X'110E' File is being declared
*------------------------------------------------------------------*
* Parameter list pointers. *
*------------------------------------------------------------------*
INPARMS DSECT
STDPARMP DS A(0) Ptr to standard format MVS parameter list
EXTPARMP DS A(0) Ptr to extended DFM parameter list
*
*------------------------------------------------------------------*
* Standard MVS parameter list for SORT usage. *
*------------------------------------------------------------------*
STDPARMS DSECT
STDPARML DS H Length of parameters
STDPARMC DS CL256 Standard parameter string
*
*
*------------------------------------------------------------------*
* Extended parameter list unique to DFM. *
*------------------------------------------------------------------*
EXTPARMS DSECT
EXTPARML DS H Length of parameters
DS H Reserved
EXTCMDCP DS H Command code point
EXTOBJCP DS H Object code point
EXTOFNLN DS H Original filename length
EXTOFN DS CL54 Original filename
EXTMFNLN DS H Modified filename length
EXTMFN DS CL54 Modified filename
EXTRSNC1 DS F Reason code 1
EXTRSNC2 DS F Reason code 2
*
END DFMQTSO
z/OS DFSMS DFM Guide and Reference
Copyright IBM Corporation 1990, 2014