An update to the screen viewing utility (for CICS)

We have found Richard Keane’s article, A screen viewing utility, published in CICS Update, extremely useful for our Help Desk facility. A modification was described in a later edition of CICS Update, to enable this utility to be CICS 4.1 compatible and to PEEK by user-id rather than by terminal-id. We have now added a further change to allow the automatic screen update every two seconds. We also tried a one-second delay, but this caused a problem on the terminal we tried to PEEK. In the original program the person doing the PEEKing had to press ENTER to retrieve the next PEEKed display. Here’s what happens – the Help Desk person logs on to a CICS terminal, clears the screen, and types PEEK USER-ID followed by the ENTER key. The next screen displayed will be the user’s terminal. In response to the PEEK command, program ITPEEK gets control and retrieves the user-id text from the originator’s terminal. It then attempts to find the terminal-id for that user-id. If the terminal-id cannot be located, an error message is sent back to the originator’s terminal and control returns to CICS, and that is the end of the story. However, if the terminal-id is located, the program starts TRANSID LOOK, passing a COMMAREA containing the user’s terminal-id, and returns to CICS. The RECEIVE in ITPEEK initially takes the data from the originator’s terminal – note this for later! The transaction-id LOOK is started on the user’s terminal. The program ITLOOK gets control next. Its first job is to check whether there is a COMMAREA attached to this terminal; if so, it needs to be saved for later. If no COMMAREA is attached, there is nothing to be saved. Next, the cursor position is saved and a RETRIEVE command performed to obtain the COMMAREA sent by ITPEEK. The terminal’s buffer is read and saved in a buffer, together with other information, and a START SHOW transaction is done with this buffer set as the COMMAREA. Now there are two possible exits. If no COMMAREA was detected at the start of ITLOOK, then there was no transaction waiting to run on this terminal, so a simple return to CICS is done. Otherwise, the transaction that was to run must be set up again by doing a return to it, specifying the COMMAREA found at the start of ITLOOK, and then returning to CICS to wait for the terminal operator to do what he was going to do before we jumped in! Transaction SHOW now gets control back on the originator’s terminal and program ITSHOW retrieves the COMMAREA, which contains the data from the user’s terminal’s buffer. A SEND command is used to display this on the originator’s terminal and a two-second delay is performed. The next thing to do is to check whether the originator has pressed PF3 – to end the loop – and, if so, simply exit to CICS. If PF3 has not been pressed then a RETURN IMMEDIATE command is executed using the INPUTMSG option. In the INPUTMSG option is the text PEEK USER-ID and the transaction-id specified is PEEKed. Once again the PEEK-LOOK-SHOW loop has been activated. The receive in ITPEEK now gets its data, not from the terminal, but from the INPUTMSG option of the return command. When the operation is complete, simply press PF3! You should ensure that the two terminals have the same number of lines and columns, or, at least, that the originator’s is the larger.

ITLOOK *********************************************************************** * PROGRAM : ITLOOK * * TRANSID : LOOK * *********************************************************************** *ASM XOPTS(NOPROLOG) DFHEISTG DSECT , DFHEISTG LOOK CSECT , DFHEIENT CODEREG=(3,8) MVC LCOMAREA(2),=H'Ø' INITIALIZE STORAGE AREAS * CHECK TO SEE IF A COMMAREA IS PRESET FOR THIS TERMINAL. IF SO WE * * MUST SAVE IT FOR THE NEXT TRANSACTION - WAITING TO RUN ON THIS TERM * LH 5,EIBCALEN COMMAREA LENGTH LTR 5,5 LENGTH ZERO ? BZ NOCOMARE YES, NO NEED TO SAVE STH 5,LCOMAREA NO, SAVE LENGTH L 4,DFHEICAP ADDRESS OF COMMAREA BCTR 5,Ø LESS ONE FOR EXECUTE CH 5,LENCOMSA CHECK LENGTH NOT TOO LARGE BH NOSHOW YES, TOO LONG, EXIT EX 5,MOVINCOM MOVE INTO SAVEAREA * RETRIEVE THE TERMINAL ID ON WHICH 'PEEK' WAS STARTED * NOCOMARE EXEC CICS RETRIEVE , X INTO(PARMS) , GET INVOKER'S TERM-ID X LENGTH(LPARMS) MVC PEEKTERM(4),TERMID INVOKER'S TERM-ID MVC LOOKTERM(4),EIBTRMID TARGET TERM-ID MVC CURSOR(2),EIBCPOSN CURSOR POS MVC LRBUFFER(2),SLRBUFER SET LENGTH OF RECEIVE BUFFER EXEC CICS RECEIVE , READ CONTENTS OF SCREEN X INTO(RBUFFER) X LENGTH(LRBUFFER) X BUFFER X ASIS X LEAVEKB LH 4,LRBUFFER LENGTH OF DATA READ AH 4,=H'1Ø' PLUS 1Ø BYTES FOR TRANS 'SHOW' STH 4,LPASDATA SAVE LENGTH * * IF THE TRANSACTION WHICH PREVIOUSLY RAN ON THIS TERMINAL WAS PSEUDO-* * CONVERSATIONAL IT WILL HAVE RETURNED TO CICS USING EXEC CICS * * RETURN TRANS-ID('XXXX'). * * WHEN THE USER ENTERED DATA TRANS-ID XXXX WOULD HAVE BEEN STARTED BY * * CICS. BECAUSE WE ARE RUNNING IN BETWEEN, WE MUST ALSO RETURN TO * * CICS, SETTING XXXX AS THE NEXT TRANSACTION TO BE STARTED. * * START TRANSACTION 'SHOW' AT INVOKER'S TERMINAL TO DISPLAY SCREEN * * STRTSHOW EXEC CICS START X TRANSID('SHOW') X TERMID(PEEKTERM) X FROM(CURSOR) X LENGTH(LPASDATA) CLC LCOMAREA(2),=H'Ø' WAS A COMMAREA PRESENT BE NOSHOW NO, RETURN NO COMMAREA EXEC CICS INQUIRE TERMINAL(EIBTRMID) NEXTTRANSID(LASTTRAN) CLC LASTTRAN(4),=CL4' ' WAS A TRANSACTION TO BE STARTED? BNE EXIT YES, RETURN WITH TRANS-ID NOSHOW EXEC CICS RETURN , NO, RETURN * RETURN TO CICS WITH TRANSID * EXIT EXEC CICS RETURN X COMMAREA(COMMAREA) X TRANSID(LASTTRAN) X LENGTH(LCOMAREA) * CONSTANTS * MOVINCOM MVC COMMAREA(*-*),Ø(4) DUMMY FOR EXECUTE SAVEREGS DC 18F'Ø' SAVE REGS AREA COMMAREA DC 3Ø72C' ' SAVE AREA FOR COMMAREA LENCOMSA DC H'3Ø72' LENGTH OF COMMAREA LCOMAREA DC H'Ø' LENGTH OF SAVED COMMAREA PARMS DS ØCL5 PASSED BY 'PEEK' TERMID DC CL5' ' INVOKER'S TERM-ID LPARMS DC AL2(*-PARMS) PEEKTERM DC CL4' ' HOLDING AREAS CURTERM DC CL4' ' CURSOR DC H'Ø' DATA PASSED TO SHOW LASTTRAN DC CL4' ' LOOKTERM DC CL4' ' RBUFFER DC 3ØØØC' ' RECEIVE BUFFER DS ØH LRBUFFER DC AL2(*-RBUFFER) LENGTH SLRBUFER DC AL2(*-RBUFFER-2) SAVE LENGTH LPASDATA DC AL2(LRBUFFER-CURSOR) LENGTH OF PASS DATA DFHEIEND END LOOK ITPEEK *********************************************************************** * PROGRAM : ITPEEK * * TRANSID : PEEK * *********************************************************************** DFHEISTG DSECT , DFHEISTG TRANSID DS CL4 MAP SCREEN FILLER DS CL1 USERID DS CL8 AAAAAAAA DS CL4Ø PEEK CSECT , EXEC CICS RECEIVE INTO(TRANSID) LENGTH(SLEN) NOHANDLE MVC TARGET,USERID MOVE IN TARGET USER-ID OC TARGET,=CL8' ' CONVERT TO UPPER CASE MVC TERMID(4),EIBTRMID SAVE INVOKER'S TERMINAL-ID EXEC CICS HANDLE CONDITION , IF TARGET TERM-ID NOT FOUND X TERMIDERR(WRONGTRM) X END(WRONGTRM) EXEC CICS INQUIRE TERMINAL START LOOP EXEC CICS INQUIRE TERMINAL (USTERM) NEXT * USERID(USERID) CLC USERID,TARGET BNE LOOP STARTLOO EXEC CICS START , START TRANSACTION LOOK X TRANSID('LOOK') , PASSING OUR TERMINAL-ID FOR X FROM(PARMS) , TRANSACTION 'SHOW' X LENGTH(LPARMS) X TERMID(USTERM) EXIT EXEC CICS RETURN , RETURN TO CICS * WRONGTRM MVC ERRTERM,TARGET MOVE TARGET NAME TO ERROR MSG EXEC CICS SEND , DISPLAY ERROR MESSAGE X FROM(EMSG) X LENGTH(LEMSG) X CTLCHAR(WCC) X ERASE EXEC CICS SEND CONTROL X FREEKB B EXIT EXIT * CONSTANTS * WCC DC X'F1' WRITE CONTROL CHARACTER SMSG DC X'1DC1' ATTRIBUTE, UNPROTECTED, MDT ON DC C'TRANSACTION LOOK STARTED FOR USER ' TARGET DC CL8' ' LSMSG DC AL2(*-SMSG) EMSG DC X'1DF2' ERROR MESSAGE 1 DC C'USER ' ERRTERM DC CL8' ' DC C' IS NOT CURRENTLY LOGGED ON ' LEMSG DC AL2(*-EMSG) PARMS DS ØCL5 COMMAREA PASSED TO 'LOOK' TERMID DC CL5' ' LPARMS DC AL2(*-PARMS) HEXNULL DS XL14'ØØ' USERMAND DS XL1'ØØ' USERNAME DS XL12'ØØ' LREC DC H'3ØØØ' SLEN DC H'57' RECORD DS 3ØØØC USTERM DS 4C END PEEK ITSHOW *********************************************************************** * PROGRAM : ITSHOW * * TRANSID : SHOW * *********************************************************************** DFHEISTG DSECT , DFHEISTG SHOW CSECT , MVC LRBUFFER(2),SLRBUFER SET LENGTH OF SEND BUFFER MVC LRECVBUF(2),SLRECVBU SET LENGTH OF RETRIEVE BUFFER EXEC CICS RETRIEVE , RETRIEVE DATA PASSED BY 'LOOK' X INTO(CURSOR) X LENGTH(LRECVBUF) LH 4,LRECVBUF LENGTH SH 4,=H'1Ø' LESS 1Ø BYTES WHICH ARE FOR US STH 4,LRBUFFER SET SEND LENGTH MVC LASTTRAN(4),NEXTTRAN TRAN NAME SCHEDULED ON TARGET EXEC CICS INQUIRE TERMINAL(PEEKTERM) USERID(PEEKED) EXEC CICS SEND , DISPLAY DATA ON SCREEN OF TARGETX FROM(RBUFFER) X LENGTH(LRBUFFER) X ERASE X CTLCHAR(WCC) EXEC CICS SEND CONTROL , SET CURSOR POSITION X FREEKB X CURSOR(CURSOR) EXEC CICS DELAY FOR SECONDS (2) CLI EIBAID,X'F3' BE EXIT EXEC CICS RETURN IMMEDIATE X TRANSID ('PEEK') X INPUTMSG (REPEAT) X INPUTMSGLEN (14) EXEC CICS RETURN , RETURN TO CICS EXIT EQU * EXEC CICS SEND , SEND 'PEEK USER-ID' WHICH IS X FROM(ENDMESS) , UNPROTECTED, ENABLING THE USER X LENGTH(LENDMSL) , TO JUST PRESS ENTER TO REINVOKE X ERASE , 'PEEK' EXEC CICS RETURN , RETURN TO CICS * CONSTANTS * DS ØF WCC DC X'F3' WRITE CONTROL CHARACTER REPEAT DC CL5'PEEK ' END MESSAGE PEEKED DC CL8' ' INFO DC C' NEXT TRANSACTION ID : ' LASTTRAN DC CL5' ' LREPEAT DC AL2(*-REPEAT) CURSOR DC H'Ø' RETRIEVE BUF.PREFIXED BY CURPOS, NEXTTRAN DC CL4' ' NEXT TRANS-ID OF TARGET TERMINAL PEEKTERM DC CL4' ' NAME OF THEN TERMINAL RBUFFER DC 3ØØØC' ' DATA OBTAINED BY 'LOOK' LRBUFFER DC AL2(*-RBUFFER) LENGTHS SLRBUFER DC AL2(*-RBUFFER-2) LRECVBUF DC AL2(LRBUFFER-PEEKTERM) SLRECVBU DC AL2(LRBUFFER-PEEKTERM) ENDMESS DC XL12'114Ø4Ø3C5D7C5F114EC31DE8' DC CL33'OK, I'm GOING then - See Yer !!!' DC XL2'1D4Ø' LENDMSL DC H'47' END SHOW

G Coates (UK) © 2006 This article was reprinted with permission.