Processing the VTAM USS MSG10 buffer
This newsletter discusses how to implement the VIRTEL VIR0021W USSTAB menu program. This program will interrogate the customers USSTAB module and create an equivalent 3270 MAP. The MAP will be passed to the VIR0010 routine where it will subsequently be converted into a HTML template and served to the browser. The generated template will provide similar functionality to that of the VTAM USSMSG10, that being a presentation screen and support for USSCMD and USSPARM entries. This allows customers to maintain their USSTAB MSG10 presentation for both VTAM and VIRTEL users without modification. The customers assembled USSTAB module, normally found in USER.VTAMLIB or an equivalent library, must be made available to VIRTEL. This can be done by either copying the module to a VIRTEL steplib library or concatenating the USER.VTAMLIB library into the VIRTEL started procedure.
Note
Replace SPTHOLT with your HLQ.
Installation instructions
Note
The following outlines the installation procedure for Virtel 4.53 onwards. For installation with Virtel 4.55 and subsequent later relaease, steps 1 through to 5 are not required as the modules will be delivered as part of the Virtel 4.55 installation.
Allocate a TRS file on the mainframe with the following JCL:
//SPTHOLTT JOB (9000),'ED...HOLT...',
// NOTIFY=&SYSUID,RESTART=*,
// CLASS=A,
// MSGCLASS=X,
// MSGLEVEL=(0,0),
// COND=(4,LT)
//*-------------------------------------------------------------------+
//* |
//* CREATE A TERSE FILE READY TO RECEIVE BINARY UPLOAD |
//* |
//*-------------------------------------------------------------------+
//DEL EXEC PGM=IEFBR14
//DDA DD DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,0),
// DSN=SPTHOLT.XMIT.LOADLIB.TRS
//S00 EXEC PGM=IEFBR14
//DDA DD DSN=SPTHOLT.XMIT.LOADLIB.TRS,DISP=(,CATLG),UNIT=SYSDA,
// SPACE=(CYL,(1,1)),DCB=(LRECL=1024,BLKSIZE=6144,RECFM=FB)
//DDB DD DSN=SPTHOLT.XMIT.LOADLIB.BIN,DISP=(,CATLG),UNIT=SYSDA,
// SPACE=(CYL,(1,1)),DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)
Upload the binary TRS file ptf5325-mvs453.trs to the mainframe and unterse the TRS file. The file can be found on the FTP website in the PUBLIC directory under /VIRTEL 4.53/PTFS. The following is an example of the JCL required to unterse the file.
//SPTHOLTD JOB DSSDUMP,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//S01 EXEC PGM=TRSMAIN,PARM=UNPACK
//SYSPRINT DD SYSOUT=*
//INFILE DD DSN=SPTHOLT.XMIT.LOADLIB.TRS,DISP=SHR
//OUTFILE DD DSN=SPTHOLT.XMIT.LOADLIB.BIN,DISP=SHR
Receive the untersed file using the TSO RECEIVE command.
- ::
receive indsn(XMIT.LOADLIB.BIN)
This will create the LOAD library SPTHOLT.XMIT.LOADLIB which should contain the following members:-
- ::
USSVIRT Default VIRTEL USSTAB VIR0021W Virtel USSTAB program EIRM00W Dummy MAP module required by VIR0021W
Copy these load members into your VIRTEL load library. They are all new members.
Apply the following zaps to the VIRTEL module VIR0010. This fix can also be found on the FTP website in the allpts-mvs453 member in the PUBLIC directory under /VIRTEL 4.53/PTFS.
*********************************************************************
* * PTF5325 MVS453 *
*
*********************************************************************
* PTF5325 MVS453
* 5325 TEST #PARM6 FOR MAP BEFORE LOADING THROUGH XLOAD
* PTF FOR VIRTEL VERSION >>>> 4.53 <<<<
CHECKSUM
NAME VIR0010
VER 1A4C 58F0,CA78 L R15,A(XLOAD)
VER 1FB2 58F0,C508 L R15,A(XLOAD)
REP 1A4C 4DE0,A920 B PATCH1
REP 1FB2 4DE0,A92E B PATCH2
IDRDATA PTF5325
NAME VIR0099
VER 0920 A920,A922,A924,A926,A928,A92A,A92C,A92E
VER 0930 A930,A932,A934,A936,A938,A93A
REP 0920 BF8F,9038 ICM R8,#PARM6 GET MAP?
REP 0924 4770,C05C BNZ + 8 PASS LOAD
REP 0928 58F0,CA78 L R15,A(XLOAD) SET LOAD IN R15
REP 092C 07FE RETRUN
REP 092E BF8F,9038 ICM R8,#PARM6 GET MAP?
REP 0932 4770,C052 BNZ + 8 PASS LOAD
REP 0936 58F0,C508 L R15,A(XLOAD) SET LOAD IN R15
REP 093A 07FE RETRUN
IDRDATA PTF5325
NAME VIR0PTF
VER 0108 00000000
REP 0108 00532500
IDRDATA PTF5325
CHECKSUM A164C619
********************************************************************
* * PTF5369 MVS453 *
* *
********************************************************************
* PTF5369 MVS453
* 5369 LOOP COPYING FILES DUE TO AN ERROR IN PTF5325
* PTF5325 IS PRE-REQUISITE
* PTF FOR VIRTEL VERSION >>>> 4.53 <<<<
CHECKSUM
NAME VIR0010
VER 1A4C 4DE0,A920 PTF5325
REP 1A4C 4DE0,A940 B PATCH3
VER 1FB2 4DE0,A92E PTF5325
REP 1FB2 4DE0,A94C B PATCH4
IDRDATA PTF5369
NAME VIR0099
VER 0940 A940,A942,A944,A946,A948,A94A,A94C,A94E
REP 0940 9180,5000,4780,A928,47F0,A920,9104,5000
VER 0950 A950,A952,A954,A956
REP 0950 4780,A936,47F0,A92E
IDRDATA PTF5369
NAME VIR0PTF
VER 0138 00000000
REP 0138 00536900
IDRDATA PTF5369
CHECKSUM 755CE17A
********************************************************************
* * PTF4369A MVS453 *
* *
********************************************************************
*
********************************************************************
* * PTF5369A MVS453 *
* *
********************************************************************
* * USER SPECIFIC - ONLY FOR SITE HAVING A VIR0021W MODULE
* * USER SPECIFIC - IF YOU HAVE VIR0021W, YOU SHOULD UNCOMMENT BELOW
*
********************************************************************
* PTF5369A MVS453
* 5369A COMPLEMENT OF PTF5369 - USER SPECIFIC
* PTF5369 IS PRE-REQUISITE
* PTF FOR VIRTEL VERSION >>>> 4.53 <<<<
CHECKSUM
NAME VIR0021W
VER 0633 1112,00
REP 0633 9192,04
IDRDATA PTF5369A
NAME VIR0PTF
VER 0138 00536900
REP 0138 00536980
IDRDATA PTF5369A
Run the following ARBO update job to add some definitions to support USSMSG10. Here we are adding new line/entry point/terminals/transaction definitions. Change LOCADDR IP address!. Transaction EDS-16A adds the support for VIR0021W which is the USSTAB support module.
//SPTHOLTA JOB 9000,'UPGRADE',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,
// REGION=0M,RESTART=*
// SET LOAD=SPTHOLT.VIRT453.LOADLIB << Change
// SET ARBO=SPTHOLT.VIRT453.ARBO << Change
//*
//* SAMPLE JOB TO ENTRIES TO ARBO TO SUPPORT USSMSG10
//* PROCESSING
//*
//CONFIG EXEC PGM=VIRCONF,PARM='LOAD,REPL',COND=(4,LT)
//STEPLIB DD DSN=&LOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//VIRARBO DD DSN=&ARBO,DISP=SHR
TERMINAL ID=EHLOC000, -
DESC='EH Psuedo Terminals', -
TYPE=3, -
COMPRESS=2, -
INOUT=3, -
REPEAT=0016
TERMINAL ID=EHVTA000, -
RELAY=*W2HPOOL, -
DESC='HTTP terminals (with relay)', -
TYPE=3, -
COMPRESS=2, -
INOUT=3, -
STATS=26, -
REPEAT=0016
LINE ID=E-HTTP, -
NAME=HTTP-EDS, -
LOCADDR=192.168.170.30:41003, - < Change this address!
DESC='HTTP line (entry point EDSHOST)', -
TERMINAL=EH, -
ENTRY=EDSHOST, -
TYPE=TCP1, -
INOUT=1, -
PROTOCOL=VIRHTTP, -
TIMEOUT=0000, -
ACTION=0, -
WINSZ=0000, -
PKTSZ=0000, -
RETRY=0010
ENTRY ID=EDSHOST, -
DESC='HTTP entry point (EDS application)', -
TRANSACT=EDS, -
TIMEOUT=0720, -
ACTION=0, -
EMUL=HTML, -
SIGNON=VIR0020H, -
MENU=VIR0021A, -
IDENT=SCENLOGM, -
EXTCOLOR=E
TRANSACT ID=EDS-00, -
NAME=EDSHOST, -
DESC='Default Directory', -
APPL=EDS-DIR, -
TYPE=4, -
TERMINAL=EHLOC, -
STARTUP=2, -
SECURITY=0, -
TIOASTA='w2h/WEB2AJAX.htm+VTAMUSS'
TRANSACT ID=EDS-03W, -
NAME='w2h', -
DESC='W2H toolkit directory (/w2h)', -
APPL=W2H-DIR, -
TYPE=4, -
STARTUP=2, -
SECURITY=0
TRANSACT ID=EDS-16A, -
NAME=VTAMUSS, -
DESC='Logon through USSTAB', -
APPL=VIR0021W, -
TYPE=2, -
TERMINAL=EHVTA, -
STARTUP=1, -
SECURITY=1, -
LOGMSG='usstab=usloc00'
After the ARBO update, start VIRTEL and check out the new definitions. In the following example a new Line using port 41003 and entry point EDSHOST is created in order to separate general Virtel users from those who will be restricted to only applications supported by the USSTAB. The new Entry Points “TIOA at Logon” to redisplay the VTAM USS tab after a user exits an application. The Entry point is restricted to only three transactions.
Fig 1. - Line Entry
The related terminal pool should be defined with a definitions to support the LUs that will maintain sessions with the VTAM applications. The terminal pool definitions look like:-
Fig 2. - Terminal definitions
The Entry Point definition looks like the following:-
Fig 3. - Entry point definitions
The transactions that are supported by this entry point are listed below:-
Fig 4. - Transaction list for the entry point
The first is the default transaction for the entry point – the same name as the entry point. Virtel, by default, will return here whenever we exit an application. To re-display the USSTAB we set the “TIOA at logon” field to point to the VTAMUSS transaction EDS-16A.
Fig 5. - Entry Point Transaction
The second transaction, EDS-03W, is a transaction the enables VIRTEL to access the W2H directory from this entry point. This is required so that web elements can be served from the W2H directory. For example the HTML page “w2h/WEB2AJAX.htm”
Fig 6. - Directory Transaction for w2h
The third and final transaction in our entry point list is the VTAMUSS transaction. It is this transaction that calls the VIR0021W utility which interrogates the VTAM USSTAB load module and display a similar page in HTML. The transaction definition looks like:-
Fig 7. - VTAMUSS transaction
Note
“Security=1” is set which will force users to logon before the USSTAB is displayed. Change this to 0 if you wish to bypass this security check.
From a browser access the VTAMUSS transaction. This can be from the VIRTEL Menu Screen or with a direct URL such as http://192.168.170.30:41003. By default the TIOA logon script associated with this entry point will call the VTAMUSS transaction which will then display the default USSTAB. This is just a sanity check to make sure that the VIR0021W module has been installed and is working correctly. See below for an example of the Virtel default USSTAB.
Fig 8. - Default USSTAB
Access an application through the following command LOGON APPLID=application. For example LOGON APPLID=MYTSO. This should take you the application specified. On exiting the application you will be returned to the VIRTEL menu and not the VTAM screen. This can be changed. See note 12.
Update the VTAMUSS transaction in the Entry Point to pass the name of your USSTAB to VIR0021W. This is done by coding the following string in the logon field. See screen shot below:-
Fig 9. - Defining the USSTAB name in the transaction
Press PF1, PF3, PF3, PF1 to save the changes. The “usstab=ussn” string will be passed through to the VIRTEL application VIR0021W. This application will load the VTAM USSTAB, interrogate it and build the necessary template to display the USSMSG10 buffer in the browser.
By reloading the http://192.168.170.30:41003 URL again the USSVTAM transaction will display the VTAM USS table identified in the “usstab=” keyword. Here is an example of the USSTAB USSN that was specified in the Logon message field.
Fig 10. - USSN Example
If the default Virtel USSTAB appears than VIRTEL hasn’t be able to locate your USSTAB load module. Check that it is either concatenated into the VIRTEL steplib or copied into the VIRTEL load library. Check the Virtel log for any error messages.
Version 1.1
Version 1.1 of VIR0021W introduced the following enhancements.
System Symbolic support
VIR0021W now supports system symbolics within the MSG10 area and in the usstab= keyword. For example in the MSG10 buffer definition any area that has a symbolic will be translated using the values defined in the SYS1.PARMLIB member IEASYMXX. The z/OS command D SYMBOLS can be use to list the defined system symbolics.
DC CL80' This is system &&SYSNAME. running on SYSPLEX &&SYSPLEX.'
would be translated and displayed as:-
DC CL80' This is system ZAMVS1 running on SYSPLEX PLEX1'
In the usstab= keyword, in the transaction definition, a symbolic can form part of the usstab name. This enables different usstabs to be loaded depending on the system. For example the following would load USSTAB1A if the symbolic &SYSCLONE. was defined as 1A.
usstab=usstab&SYSCLONE.
Feedback support
A new keyword has been added to support feedback within the support module. If errmsg=y is coded then any error messages will be displayed on line 24. If the USSTAB is uses row 24 for presentation purposes then the errmsg= keyword should not be used. Error reporting will report on invalid application selection and invalid key usage. Any other error messqges will be reported to the Virtel SYSLOG. For example:-
usstab=usstab&Sysclone.,errmsg=y
Will load a USSTAB module depending on the &SYSCLONE. system symbolic value and report error messages to line 24.
Constraints
VIR0021W attempts to simulate the functionality of USSMSG10 processing. It doesn’t distinguished between PL1 and BAL code strings. So, for example on the above USSTAB, you could enter LOGON APPLID(TSO) or LOGON APPLID=TSO. Both would be accepted.
Use only SBA Buffer addresses. Do not use displacement addresses such as AL2(((24-1)*80)+(80-1)).
The USSTAB module should only have ONE UNPROTECTED output field. This is used as the command area. It should not exceed 78 bytes. Use the tab key to check.
To control colours use the extended attribute options rather than the basic field attributes. Some of the basic attributes imply unprotected fields.
The SCAN parameter must be included on the BUFFER statement:-
MSG10 USSMSG MSG=10,BUFFER=(MSG10BUF,SCAN)
The cursor position must be preceded by a SBA:-
DC X'11',AL2(((24-1)*80)+(10-1)) R=23,C=80
DC X'1D40' UNPROTECTED
DC X'13' INSERTCURSOR
Failure to comply with these constraints will result in unpredicatble behaviour.
Messages
VIR2101E UNABLE TO LOAD A USSTAB
Module : VIR0021W
Meaning : Virtel was unable to build a MAP from the supplied USS load module.
Action : Check the VTAM USS module has been assembled correctly and is available in the VIRTEL STEPLIB concatenation. See the topic on constraints for further information.
VIR2102W UNABLE TO LOAD THE [TCT | TRANSACTION] USSTAB usstab. DEFAULT USSTAB USSVIRT WILL BE USED.
Module : VIR0021W
Meaning : Virtel was unable to load the USS table as defined either in the transaction or TCT.
Action : Check that the correct USSTAB has be defined and that the relevant load module is accessible through the VIRTEL STEPLIB concatenation.