Marc Niegowski Systems Programmer Consultant - 370, 390, z Assembler Processing console MODIFY/F and STOP/P commands

Many mainframe tasks such as server tasks (daemons) execute for long periods of time. In order to communicate with such tasks, one could leave an outstanding WTOR on the console. To terminate a task having an outstanding WTOR, one would respond to the WTOR with the appropriate shutdown command. Another technique would be to honor the console STOP or P command. Additionally, one could honor the console MODIFY or F command to alter the operation of the task.

This tutorial will attempt to illustrate a technique to capture console STOP or P commands and MODIFY or F commands. It uses the authorized assembler services EXTRACT and QEDIT macros and must therefore be bound (link edited) into an APF authorized library with AC=1.

The following is a fully functional code example of a program that examines and processes z/OS console MODIFY or F and STOP or P commands:

CMDTASK TITLE 'Sample task to illustrate console command processing' *---------------------------------------------------------------------* * Private code Copyright preamble. * *---------------------------------------------------------------------* CSECT , Private Code CSECT. AMODE 31 Set 31-Bit addressing mode. RMODE ANY Set Any (24 or 31-Bit) residency. SPACE , DC C'Assembly date && time: &SYSDATE &SYSTIME ' DC C'Copyright (C) 1993-2006, Marc Niegowski ' DC C'Systems Programmer At Large ' DC C'All Rights Reserved.' SPACE , * If you assemble and bind this module as CMDTASK into an * authorized library and START/S it, you can STOP/P it with a * "P CMDTASK" command. If you submit it as a job, you can * STOP/P it with a "P jobname" command. SPACE , * If this task was started with a START/S command, you can also * send if MODIFY/F commands like "F CMDTASK,PARM=(ANYTHING)". If * you have submitted it as a job, the MODIFY/F commands take the * form "F jobname,PARM=(ANYTHING)". SPACE , *---------------------------------------------------------------------* * Register equates. * *---------------------------------------------------------------------* REGEQU , Generate register equates. EJECT *---------------------------------------------------------------------* * Main CSECT and entry point. * *---------------------------------------------------------------------* CMDTASK CSECT , Main CSECT. CMDTASK AMODE 31 Set 31-Bit addressing mode. CMDTASK RMODE ANY Set Any (24 or 31-Bit) residency. SPACE , ENTRY CMDTASK CSECT entry point. BAKR R14,0 Store callers regs to system stack. LR R12,R15 Load A(CSECT base). USING CMDTASK,R12 Establish CSECT addressability. SPACE , STORAGE OBTAIN, Allocate some working storage... C ADDR=(R11), ...for a register save area ... C LENGTH=WSDL ...(RSA), Stack, Buffers, etc.. SPACE , USING WSD,R11 Establish WSD addressability. LA R2,1(,R11) Load A(Working Storage + 1) to R2. LA R3,WSDL-1 Load L'Working Storage - 1 to R3. LR R4,R11 Load A(Working storage) to R4. LA R5,1 Load 1 to R5. MVCL R2,R4 Init working storage to X'00's. LA R8,WSDSTACK Base the stack with R8. SPACE , ST R13,WSDR13P Save A(Prior RSA). MVC WSDR13,=C'F1SA' Set Format 1 Save Area for others. LA R13,WSDRSA Load A(RSA) to R13. SPACE , MVC WSDWTOL,WTOL Move list form WTO to working stg. MVC WSDTIMEL,TIMEL Move list form TIME to working stg. MVC WSDEXTL,EXTRACTL Move list form EXTRACT to work stg. SPACE , BAS R14,TS0010 Call task start routine. *DUMMY* BAS R14,ST0010 Call task STIMER routine. BAS R14,EX0010 Call task EXTRACT routine. CM0010 DS 0H BAS R14,SC0010 Call CIB examination routine. TM WSDFLAG,FSTOP Did we get a STOP/P command? BO CM0020 Yes, take branch. WAIT ECBLIST=WSDECBLA Wait for another console command. B CM0010 Check the command that was issued. SPACE , CM0020 DS 0H BAS R14,TT0010 Call task termination routine. SPACE , L R13,WSDR13P Restore original R13. DROP R11 Drop WSD. SPACE , STORAGE RELEASE, Free working storage area (WSD). C ADDR=(R11), C LENGTH=WSDL SPACE , XR R15,R15 Clear return code. PR Return to caller. EJECT *---------------------------------------------------------------------* * Task start. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , TS0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , BAS R14,DT0010 Get system date and time. MVC WSDMSG(L'WTOT001+2),WTOM001 MVC WSDMSG+22(L'WSDEDTIM-1),WSDEDTIM+1 MVC WSDMSG+41(L'WSDEDDTE-2),WSDEDDTE+2 LA R2,WSDMSG Load A(Task start message). SPACE , WTO TEXT=((R2)), WTO message address in R2. C MF=(E,WSDWTOL) WTO execute form. SPACE , TS9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R11 Drop WSD. EJECT *---------------------------------------------------------------------* * Task termination. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , TT0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , BAS R14,DT0010 Get system date and time. MVC WSDMSG(L'WTOT002+2),WTOM002 MVC WSDMSG+22(L'WSDEDTIM-1),WSDEDTIM+1 MVC WSDMSG+41(L'WSDEDDTE-2),WSDEDDTE+2 LA R2,WSDMSG Load A(Task ended message). SPACE , WTO TEXT=((R2)), WTO message address in R2. C MF=(E,WSDWTOL) WTO execute form. SPACE , TT9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R11 Drop WSD. EJECT *---------------------------------------------------------------------* * Retrieve date and time from the system. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , DT0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , XC WSDDTME,WSDDTME Clear the time and date field. SPACE , TIME DEC, Return time in decimal format. C WSDDTME, 16 Byte time and date field. C ZONE=LT, Return local time as opposed to GMT.C LINKAGE=SYSTEM, System linkage as opposed to SVC. C DATETYPE=MMDDYYYY, Date format. C MF=(E,WSDTIMEL) Execute form TIME macro. SPACE , OI WSDDTME+6,X'0C' Set a sign for the time. MVO WSDDTME+7(5),WSDDTME+8(4) Offset the packed date. NI WSDDTME+11,X'F0' Clear the sign nybble. OI WSDDTME+11,X'0C' Set a sign for the date. SPACE , MVC WSDEDTIM,TIMEMASK Move out the TIME edit mask. ED WSDEDTIM,WSDDTME Edit the time. MVC WSDEDDTE,DATEMASK Move out the DATE edit mask. ED WSDEDDTE,WSDDTME+7 Edit the date. SPACE , DT9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R11 Drop WSD. EJECT *---------------------------------------------------------------------* * Set STIMER to place the task into a wait. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , ST0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , MVC WSDINTVL,=F'6000' 6000 * 1/100 = 60 Seconds. SPACE , STIMER WAIT, Set a WAIT type STIMER. C BINTVL=WSDINTVL A(Binary timer interval). SPACE , ST9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R11 Drop WSD. EJECT *---------------------------------------------------------------------* * Extract the Communications Scheduler communications list. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , EX0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , EXTRACT WSDCOMA, A(Comm. sched. communications list).C 'S', Use current TCB address. C FIELDS=(COMM), Return Comm. sched. comm. list. C MF=(E,WSDEXTL) Execute form EXTRACT macro. SPACE , EX9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R11 Drop WSD. EJECT *---------------------------------------------------------------------* * Examine the CIB for STOP/P and MODIFY/F commands. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , SC0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , ICM R10,B'1111',WSDCOMA Insert A(COM). BZ SC9000 Take branch if no A(COMM). USING COM,R10 Establish COMM addressability. SPACE , ICM R9,B'1111',COMCIBPT Insert A(CIB). BNZ SC0040 We have a CIB, examine it. USING CIB,R9 Establish CIB addressability. SPACE , SC0030 DS 0H Make a CIB. QEDIT ORIGIN=COMCIBPT, A(CIB chain for this task). C CIBCTR=16 Number of CIBs for this task. SPACE , * Note: A CIBCTR of zero means that no MODIFY/F commands will be * accepted. CIBCTR can be between 0 and 255. A number * greater than 0 means that up to that number of MODIFY/F * commands can be chained. A STOP/P command automatically * sets the CIBCTR to 0 so that no more commands will be * accepted. SPACE , L R1,COMECBPT Load A(COM ECB). O R1,ECBLEND Mark end of ECB list. ST R1,WSDECBLA Store A(ECB list). B SC9000 Exit routine. SPACE , SC0040 DS 0H Examine the CIB. CLI CIBVERB,CIBMODFY Was it a MODIFY/F command? BNE SC0050 No, take branch. BAS R14,MD0010 Yes, process MODIFY/F command. B SC0060 Branch around STOP/F check. SPACE , SC0050 DS 0H CLI CIBVERB,CIBSTOP Was it a STOP/P command? BNE SC0060 No, take branch. OI WSDFLAG,FSTOP Set the STOP/P flag. SC0060 DS 0H QEDIT ORIGIN=COMCIBPT, A(CIB chain for this task). C BLOCK=(R9) Free this CIB. SPACE , TM WSDFLAG,FSTOP Was this CIB for a STOP/P command? BNO SC0030 No, take branch. SPACE , BAS R14,DT0010 Get system date and time. MVC WSDMSG(L'WTOT003+2),WTOM003 MVC WSDMSG+22(L'WSDEDTIM-1),WSDEDTIM+1 MVC WSDMSG+41(L'WSDEDDTE-2),WSDEDDTE+2 LA R2,WSDMSG Load A(Task stopped message). SPACE , WTO TEXT=((R2)), WTO message address in R2. C MF=(E,WSDWTOL) WTO execute form. SPACE , SC9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R9,R10,R11 Drop CIB, COM, WSD. EJECT *---------------------------------------------------------------------* * Process CIB MODIFY/F commands. * *---------------------------------------------------------------------* SPACE , * Call with: R10 - A(COM) * R9 - A(CIB) SPACE , USING WSD,R11 Establish WSD addressability. USING COM,R10 Establish COM addressability. USING CIB,R9 Establish CIB addressability. SPACE , MD0010 DS 0H Routine entry point. ST R14,0(,R8) Store return address to stack. LA R8,4(,R8) Increment stack pointer. SPACE , MD0020 DS 0H Process MODIFY/F command. BAS R14,DT0010 Get system date and time. MVC WSDMSG(L'WTOT004+2),WTOM004 MVC WSDMSG+22(L'WSDEDTIM-1),WSDEDTIM+1 MVC WSDMSG+41(L'WSDEDDTE-2),WSDEDDTE+2 LA R2,WSDMSG Load A(Task modified message). SPACE , WTO TEXT=((R2)), WTO message address in R2. C MF=(E,WSDWTOL) WTO execute form. SPACE , MD0030 DS 0H Extract MODIFY/F data. MVC WSDMSG+2(L'WTOT005),WTOT005 LH R3,CIBDATLN Get MODIFY/F data from CIB. CHI R3,126-L'WTOT005 Is data length > max msg length? BNH MD0040 No, take branch. LA R3,126-L'WTOT005 Yes, set max msg length & truncate. SPACE , MD0040 DS 0H LTR R4,R3 Was there any MODIFY/F data? BZ MD0050 No, take branch. BCTR R3,0 Decrement it for MVC. LA R2,CIBDATA Load A(MODIFY/F data). LA R1,WSDMSG+2+L'WTOT005 EX R3,MVCEX Move MODIFY/F data to the message. LA R4,L'WTOT005(,R4) Add the message header length. STH R4,WSDMSG Store the message length. LA R2,WSDMSG Load A(WTO message). SPACE , WTO TEXT=((R2)), WTO message address in R2. C MF=(E,WSDWTOL) WTO execute form. SPACE , MD0050 DS 0H Run CIB chain. ICM R7,B'1111',CIBNEXT Is there another chained CIB? BZ MD9000 No, take branch. SPACE , * Note: The caller will delete the last CIB on the chain. SPACE , QEDIT ORIGIN=COMCIBPT, A(CIB chain for this task). C BLOCK=(R9) Free this CIB. SPACE , LR R9,R7 Load A(Next CIB). CLI CIBVERB,CIBMODFY Is is a MODIFY/F command? BE MD0030 Yes, take branch and process it. B MD0050 No, take branch and delete it. SPACE , MD9000 DS 0H Routine exit. AHI R8,-4 Decrement stack pointer. L R14,0(,R8) Restore return address. BR R14 Return to caller. SPACE , DROP R9,R10,R11 Drop CIB, COM, WSD. EJECT *---------------------------------------------------------------------* * Literal pool origin and program constants. * *---------------------------------------------------------------------* USING WSD,R11 Establish WSD addressability. SPACE , CNOP 0,4 Fullword alignment. MVCEX MVC 0(0,R1),0(R2) General purpose MVC to execute. SPACE , WTOL WTO TEXT=, List form WTO. C ROUTCDE=(2,11), Console & Programmer Information. C MCSFLAG=(BRDCST), Broadcast to all consoles. C DESC=(6), Job Status Descriptor Code. C MF=L List form macro. WTOLLEN EQU *-WTOL Length of this list form WTO. SPACE , WTOM001 DC AL2(L'WTOT001) WTOT001 DC C'CMDTASK started at HH:MM:SS.thmiju on MM/DD/YYYY.' WTOM002 DC AL2(L'WTOT002) WTOT002 DC C'CMDTASK ended at HH:MM:SS.thmiju on MM/DD/YYYY.' WTOM003 DC AL2(L'WTOT003) WTOT003 DC C'CMDTASK stopped at HH:MM:SS.thmiju on MM/DD/YYYY.' WTOM004 DC AL2(L'WTOT004) WTOT004 DC C'CMDTASK modified at HH:MM:SS.thmiju on MM/DD/YYYY.' WTOM005 DC AL2(L'WTOT005) WTOT005 DC C'CMDTASK modify data: ' SPACE , TIMEMASK DC XL16'F021207A20207A20204B202020202020' DATEMASK DC XL12'F02120206120206120202020' SPACE , CNOP 0,4 Fullword alignment. SPACE , TIMEL TIME LINKAGE=SYSTEM, System linkage as opposed to SVC. C MF=L List form macro. TIMELLEN EQU *-TIMEL Length of this list form TIME macro. SPACE , CNOP 0,4 Fullword alignment. SPACE , EXTRACTL EXTRACT 0, Extract target address (Dummy). C 'S', Use the current TCB. C FIELDS=(COMM), A(Comm sched. communications list). C MF=L List form macro. EXTRALEN EQU *-EXTRACTL Length of this list form EXTRACT. SPACE , FSTOP EQU X'01' Task STOP/P flag mask. CNOP 0,4 Fullword alignment. ECBLEND DC XL4'80000000' End of ECB list. SPACE , LTORG , Literal pool origin. SPACE , *---------------------------------------------------------------------* CMDTASKX EQU *-1 End of module. SPACE , DROP R11,R12 Drop WSD and CSECT base. EJECT *---------------------------------------------------------------------* * Working storage area DSECT. * *---------------------------------------------------------------------* WSD DSECT , WSDRSA DS 18F Register save area. ORG WSDRSA+4 Set origin to R13 save word. WSDR13 DS F R13 save word. ORG , Reset origin. WSDR13P DS F Previous R13 save word. WSDSTACK DS 16F Subroutine save stack. WSDCOMA DS A A(Comm. sched. cummincations list). WSDECBLA DS A A(ECB to wait for console commands). WSDINTVL DS F STIMER interval in 1/100 seconds. WSDDTME DS PL16 Time and date from TIME macro. WSDEDTIM DS XL16 Edited time. WSDEDDTE DS XL12 Edited date. WSDMSG DS AL2,CL126 Console message. WSDEXTL DS XL(EXTRALEN) Space for list form EXTRACT. CNOP 0,4 Fullword alignment. WSDTIMEL DS XL(TIMELLEN) Space for list form TIME. CNOP 0,4 Fullword alignment. WSDWTOL DS XL(WTOLLEN) Space for list form WTO. WSDFLAG DS XL1 Task processing flags. WSDL EQU ((*-WSD+7)/8)*8 Length of DSECT to nearest dblword. EJECT *---------------------------------------------------------------------* * Communications Parameter List DSECT. * *---------------------------------------------------------------------* COM DSECT , IEZCOM , IEZCOM macro. EJECT *---------------------------------------------------------------------* * Command Input Buffer DSECT. * *---------------------------------------------------------------------* CIB DSECT , IEZCIB , IEZCIB macro. SPACE , *---------------------------------------------------------------------* END , End of assembly. PUNCH '*Binder option overrides' PUNCH ' SETOPT PARM(REUS=RENT,EXTATTR(APF,PGM))' PUNCH ' SETOPT PARM(GID=DEVEL01,UID=DEVEL01,AC=1)' PUNCH '*Module addressability and residency options' PUNCH ' MODE AMODE(31)' Binder 31-Bit addressing mode. PUNCH ' MODE RMODE(ANY)' Binder 24 or 31-bit residency. PUNCH ' ENTRY CMDTASK' Binder entry statement. PUNCH ' NAME CMDTASK(R)' Binder module name statement. END , End of Binder/Linkage Editor cards.

Put it together using the following Assembler and Binder Job-Stream as an example. Modify the Job-Stream as necessary to suit your environment:

To execute this CMDTASK tutorial program as a submitted job, you can use the following sample JCL. Modify the JCL as necessary to suit your environment:

Below is a section of the console messages from submitting the above job stream. The console MODIFY or F and STOP or P commands are highlighted in boldface.

To execute this CMDTASK tutorial program as a started task (S CMDTASK or START CMDTASK from the console), you can use the following sample JCL procedure. Modify the JCL procedure as necessary to suit your environment:

Below is a section of the console messages from starting the above procedure. The console START or S, MODIFY or F and STOP or P commands are highlighted in boldface.

If you wish to experiment with the files in this tutorial and would rather download the samples than cut and paste them from this page, you can download the cmdtask.samples.pds.xmit.zip file. Unzip this file and send it to your host TSO session using your favorite transmission method (FTP or IND$FILE, for example) using a record length of 80 and a record format of fixed (or fixed blocked as long as the blocksize is a multiple of the record length).