System SAMPLIB member DFMXSORT, for example, SYS1.SAMPLIB(DFMXSORT)
shown in Figure 1, shows how a DFM
DataAgent can be written in assembler language to invoke SORT.
Figure 1. DFM DataAgent Sort Sample Part 1 of 7
TITLE 'DFMXSORT - DFM DataAgent Sort Sample'
*/********************************************************************
*/*PROPRIETARY V3 STATEMENT *
*/*LICENSED MATERIALS - PROPERTY OF IBM *
*/*5695-DF1 *
*/*(C) COPYRIGHT 1997 IBM CORP. *
*/*END PROPRIETARY V3 STATEMENT *
*/********************************************************************
*/********************************************************************
*/* *
*/* $MOD(DFMXSORT) COMP(5695-DF120) *
*/* *
*/* MODULE NAME: DFMXSORT *
*/* *
*/* DESCRIPTION: DFM DataAgent Sample Routine (SORT) *
*/* *
*/* 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 SORT. It is *
*/* implemented with a basic function that assumes the input *
*/* filename matches the SORTIN DD statement. It changes the *
*/* filename from SORTIN to SORTOUT so that any retrieval through *
*/* DFM will retrieve the sorted data rather than the original. *
*/* *
*/* Code commentary is provided to show how the *
*/* function could be extended to use the input filename for *
*/* dynamic allocation and to derive an output filename. The *
*/* commentary also discusses how this DataAgent could request *
*/* that it be called again at file close time to access and *
*/* possibly write the output file's data to the original file. *
*/* *
*/* 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. SORT error messages will be in the JOBLOG. *
*/* *
Figure 2. DFM DataAgent Sort Sample 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 *
*/* STATE: Problem program, non-APF-authorized *
*/* LOCATION: Link library *
*/* *
*/* ENTRY POINT: DFMXSORT *
*/* *
*/* PURPOSE: Show that a DataAgent routine can invoke SORT. *
*/* LINKAGE: Called by Distributed FileManager. *
*/* INPUT: Refer to the DFM Guide and Reference for a general *
*/* description of the parameter list format. *
*/* *
*/* 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 = 8 *
*/* 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 *
*/********************************************************************
DFMXSORT AMODE 31
DFMXSORT RMODE ANY
DFMXSORT CSECT
Figure 3. DFM DataAgent Sort Sample Part 3 of 7***********************************************************************
* This program is used as a DataAgent routine to get control *
* when a workstation's SdU application opens a remote MVS file *
* with a filename suffix specifying "agent(dfmxsort)". The file is *
* assumed to be in the format of the sample file created earlier. *
* The input file is sorted and the filename is then changed to the *
* filename of the sort output file. This results in the SdU *
* application's retrieving a sorted subset of the records as if *
* they came from the original file. *
* *
* An alternative invocation method is provided by SdU through *
* the DFMACALL sample application. Refer to it for details. *
* *
* The reason code can be set to -1 to force entry at the file's *
* delete declaration time when adding extended function. *
***********************************************************************
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
RTN EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
SAVE (14,12) SAVE REGISTERS
BALR 12,0 BRANCH AND LINK REG.
USING *,12 USE REG 12
ST 13,SAVEAREA+4 SAVE BACKWARD POINTER
LA 14,SAVEAREA SET FORWARD PT.ER IN CALLER SAVE AREA
ST 14,8(13)
LR 13,14 SET OUR SAVE AREA
*------------------------------------------------------------------*
* Determine whether we are defining or deleting the file *
* declaration (i.e. previous to OPEN or after CLOSE). *
*------------------------------------------------------------------*
LR R3,R1 Save original parameter pointers
SR R15,R15 Clear error code
USING INPARMS,R3 Address of MVS parameter list
L R4,EXTPARMP Point to DFM DataAgent parameters
USING EXTPARMS,R4 Base of DFM DataAgent parameters
CLC EXTOBJCP,FILNAM Is file being processed?
BNE EXIT No, exit
Figure 4. DFM DataAgent Sort Sample Part 4 of 7*------------------------------------------------------------------*
* Called for a file–see whether declaration or delete *
* declaration. *
*------------------------------------------------------------------*
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 'DFMXSORT: Unknown command code.'
LA R15,12
B EXIT
*
*------------------------------------------------------------------*
* DCLFIL Processing *
*------------------------------------------------------------------*
DODCLFIL EQU *
*------------------------------------------------------------------*
* Enhanced function: *
* Set sort input filename from input filename. *
* Set sort output filename to input filename. *
* If output filename is greater than 40 characters then do. *
* Locate last component of filename. *
* If last component of filename is < 4 then *
* Locate last 2 components of filename. *
* If last component(s) are equal to ".SRT" then *
* Replace last component(s) with ".SR2". *
* Else *
* Replace last component(s) with ".SRT". *
* end. *
* Else *
* Append ".SRT" to output filename. *
* Allocate sort input as DISP=SHR. *
* Allocate sort output as DISP=(NEW,CATLG). *
*------------------------------------------------------------------*
*------------------------------------------------------------------*
* Invoke DFSORT with 31-bit parameter list *
*------------------------------------------------------------------*
LR R1,R3 Fetch address of std parm list
MVC EXTPARMP,=F'-1' End of list
LINK EP=SORT Invoke DFSORT
LTR R15,R15 Check for SORT failure
BNZ SORTERR Branch if error
*
*------------------------------------------------------------------*
* Enhanced function: *
* Set modified filename generated for output file allocation. *
* Set reason code to -1 to force recall for DELDCL. *
*------------------------------------------------------------------*
*
Figure 5. DFM DataAgent Sort Sample Part 5 of 7*------------------------------------------------------------------*
* Return modified filename and filename length to DFM. *
*------------------------------------------------------------------*
LH R2,EXTOFNLN Get original (input) name length
CH R2,MAXIFNLN Ensure maximum is not exceeded
BH OFNISOK Branch–file name is left alone
CH R2,MINIFNLN Ensure minimum is met
BL OFNISOK Branch–file name is left alone
LA R1,EXTOFN Point to beginning of orig fn
AR R1,R2 Point to end
LH R15,MINIFNLN Get length of trigger in name
SR R1,R15 Backup to where trigger appears
BCTR R15,0 Decrement for execute
EX R15,COMPNAME Compare last part of name
BNE OFNISOK Branch–no trigger at name end
* Original file name meets qualifications–modify file name.
LA R3,EXTMFN Set pointer to modified file name.
LR R1,R2 Set length of filename.
SH R1,MINIFNLN Backup to trigger (=root end)
BCTR R1,0 Decrement for execute
EX R1,MOVENAME Move input name beginning to output
LA R1,1(R1) Restore length
AR R3,R1 Point to end of root
LH R15,MODIFLEN Get length of modifier
BCTR R15,0 Decrement for execute
EX R15,CHANGENM Change name to root + modifier
SH R2,MINIFNLN Decrement trigger length
AH R2,MODIFLEN Add modifier length
STH R2,EXTMFNLN Set output name length
OFNISOK EQU * Here if changed/no change to do
SR R15,R15 Exit with no error
B EXIT Exit DataAgent DCLFIL routine
COMPNAME CLC 0(0,R1),TRIGGER Compare name to trigger string
MOVENAME MVC EXTMFN(0),EXTOFN Move original name to modified name
CHANGENM MVC 0(0,R3),MODIFIER Move modifier string to end of name
*
*------------------------------------------------------------------*
* SORT error occurred–refer to JOBLOG for details. *
*------------------------------------------------------------------*
SORTERR EQU *
LR R2,R15 Save SORT code
ST R0,EXTRSNC2 Save SORT reason code
WTO 'DFMXSORT: SORT failure.'
LR R15,R2 Exit with error
B EXIT Exit DataAgent routine
*
Figure 6. DFM DataAgent Sort Sample Part 6 of 7*------------------------------------------------------------------*
* DELDCL Processing *
*------------------------------------------------------------------*
DODELDCL EQU *
WTO 'DFMXSORT: Can delete IBMUSER.DFMXSORT.SORTOUT now.'
*------------------------------------------------------------------*
* Enhanced function: *
* Copy the changes to the permanent file. *
*------------------------------------------------------------------*
SR R15,R15 Exit with no error
B EXIT Exit with return code from Sort
*------------------------------------------------------------------*
* Exit *
*------------------------------------------------------------------*
EXIT EQU *
L 13,4(,13) GET RETURN ADDRESS
RETURN (14,12),RC=(15) RESTORE REGS,FLAG SAVEAREA,SET RC
SAVEAREA DC 18F'00'
LTORG
*
*------------------------------------------------------------------*
* Define input parameters. *
*------------------------------------------------------------------*
* In this case, the standard format MVS parameter list should be*
* a halfword length field followed by a DFSORT extended *
* parameter list. For example, Sort by ascending characters in *
* columns 17-22 is: *
* SORT FIELDS=(17,6,CH,A) *
*------------------------------------------------------------------*
*
*------------------------------------------------------------------*
* 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
*------------------------------------------------------------------*
* Local Constants *
*------------------------------------------------------------------*
MAXIFNLN DC H'53' Maximum allowing for trigger->modifier
MINIFNLN DC H'6' Minimum orig name len (= len of trigger)
TRIGGER DC CL6'SORTIN' Trigger in input filename
MODIFLEN DC H'7' Length of modifier
MODIFIER DC CL7'SORTOUT' Modifier for output filename
Figure 7. DFM DataAgent Sort Sample Part 7 of 7*------------------------------------------------------------------*
* 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 DFMXSORT
z/OS DFSMS DFM Guide and Reference
Copyright IBM Corporation 1990, 2014