Virtual Machine Tool SetVM Multiple Logical Terminal Session Emulator |
VMRSM Installation Page.
1.0 Program Description
1.1 Design Theory
1.3 Program Flow Main
1.4 Program Flow (Secondary Guest Facility)
1.5 Program Flow (I/O to dialed terminal)
1.6 Recovery after Normal/Test Key depressed.
1.7 Updating of non-displayed session
2.0 Installation and Operation
2.1 Define Virtual Machine for MLTS
2.11 Performance Recommendations
2.2 Service Machine PROFILE EXEC
2.3 Invocation EXEC
2.4 Operational Commands and PF keys
4.0 Program Product Exceptions
5.0 Error Messages
9.0 Disclaimer
11.1 Design Theory
This program provides a facility to simulate much of the functionthe
of the multiple logical terminal features of the IBM 3174 Terminal
Control Unit via the VM Logical Device Facility.
A single virtual machine acts as the MLTS server. This server will
will establish and maintain up to 8 logical terminal sessions with CP,
drive all I/O to the dialed port, and maintain save areas for each
logical session.
* NOTE * NOTE * NOTE * NOTE * NOTE * NOTE * NOTE * NOTE * NOTE * NOte *
** CURRENTLY ONLY 4 DIALED PORTS ARE DEFINED AND SUPPORTED
When a terminal 'DIALS' in to the service machine you receive the
normal connection message posted by CP. Upon the first I/O attention
interrupt, the MLTS facility performs a DIAGNOSE 8C to access the
device dependant characteristics of the dialed device. The CTS Logo
will then be displayed and prompt the user for the number of concurrent
logical sessions desired (default is 2), and the selection of a session
TOGgle key (default is PA2), and the optional selection of a backward
toggle key (no default). After this point a logical device
INITIATE builds the first session based upon the return of the diagnose
and the user selected parameters.
Each dialed port will have up to 8 logical sessions built. A
buffer is kept for each session and this buffer is updated whenever
an ACCEPT of data is required by CP for this logical display. The
current session display is updated upon the terminal surface.
Upon toggling through the logical sessions, before the next session
is displayed, the currently displayed session is retrieved from the
display surface by way of a READ BUFFER command and saved with status
in a unique buffer. Some extended features are preserved. Following
the save, the next sequential session established is then restored
from its storage buffer and presented to the physical display surface.
If a session is updated while it is not the session being displayed
then up to 32 updates along with the initial saved screen will be
saved (given the updates can be accomodated by the storage buffers)
All functions performed on the displayed session are the same as
would be without the MLTS except for the "jump-keys". These keys have
to be reserved for exclusive use by the MLTS to signal session jumps.
Detachment of your sessions from the MLTS server is accomplished
by disconnecting or logging off each of the sessions, then entering
the MLTS command "LDEVEXIT" from the VM Logo (or next screen).
Disconnection from the MLTS server is accomplished the MLTS command
"LDEVDISC" from the VM Logo (or next screen).
11.3 Program Flow Main
TERMINAL SERVICE MACHINE CP Logical Dev
Facility
Define GRAFs and
initialize program.
<...WAIT...>
DIAL ------> I/O Interrupt
Post dialed by CP Prepare for ATTN
<...WAIT...>
Enter Key ------> I/O Interrupt
Perform DIAG 8C.
Determine 3270 type
<------ Write CTS LOGO
Post LDEV characteristics
<...WAIT...>
Enter or PF,PA key ------> I/O Interrupt
<-----> Perform Read Mod
Set "toggle" keys
<...WAIT...>
Enter Key ------> I/O Interrupt
Perform INITIATE -----> LogDev Fac
Update dialed device
matrix.
<...WAIT...>
NEWSESS:
External Interrupt <----- LogDev Fac
Perform ACCEPT data. <----- LogDev Fac
VM Logo or other <------ Write data recvd
displayed. to dialed terminal.
<...WAIT...>
Enter Key ------> I/O Interrupt
<-----> Perform Read Mod
Perform PRESENT data -----> LogDev Fac
<...WAIT...>
External Interrupt <----- LogDev Fac
<...WAIT...>
. . .
. . .
. . .
Toggle Key ------> I/O Interrupt
AID 'xx'
<-----> Read Buffer
Store session buffer.
Set up for next session.
If previous session exist
Goto RESTSESS.
Perform DIAG 8C.
Perform INITIATE -----> LogDev Fac
Update dialed device
matrix.
Goto NEWSESS.
RESTSESS:
Restore next seq session
Previous Display <------ Write to Dialed device.
<...WAIT...>
'ldevexit' ------> I/O Interrupt
Perform Read Mod
Perform TERMINATE -----> LogDev Fac
External Interrupt <----- LogDev Fac
Dropped Msg <------ CP RESET GRAF
VM LOGO displayed <...WAIT...>
'ldevdisc' ------> I/O Interrupt
Perform Read Mod
Dropped Msg <------ CP RESET GRAF
VM LOGO displayed <...WAIT...>
11.4 Program Flow (Dialed into second service machine such as VTAM,
PASSTHRU, CICS, etc)
TERMINAL SERVICE MACHINE CP Logical Dev
Facility
Define GRAFs and
initialize program.
<...WAIT...>
DIAL ------> I/O Interrupt
Post dialed by CP Prepare for ATTN
<...WAIT...>
Enter Key ------> I/O Interrupt
Perform DIAG 8C.
Perform INITIATE -----> LogDev Fac
Update dialed device
matrix.
<...WAIT...>
NEWSESS:
External Interrupt <----- LogDev Fac
Perform ACCEPT data. <----- LogDev Fac
VM Logo or other <------ Write data recvd
displayed. to dialed terminal.
<...WAIT...>
DIAL Command ------> I/O Interrupt
<-----> Perform Read Mod
Perform PRESENT data -----> LogDev Fac
<...WAIT...>
External Interrupt <----- LogDev Fac
Perform ACCEPT data. <----- LogDev Fac
VTAM, Passthru <------ Write data recvd
or other logo to dialed terminal.
<...WAIT...>
. . .
. . .
UNDIAL, RSET ------> I/O Interrupt
(disconnect)
<-----> Perform Read Mod
Perform PRESENT data -----> LogDev Fac
<...WAIT...>
External Interrupt <----- LogDev Fac
CP Requests Terminate <----- LogDev Fac
(unlock keyboard) <------ Write unlock datastream
to dialed terminal.
<...WAIT...>
Enter Key ------> I/O Interrupt
Perform DIAG 8C.
Perform INITIATE -----> LogDev Fac
Update dialed device
matrix.
<...WAIT...>
11.5 Program Flow (I/O to dialed terminal)
READ Operation:
TERMINAL SERVICE MACHINE CP Logical Dev
Enter Key ------> I/O Interrupt
------> Perform Read Mod
if CC^0 then test and re-drive
<..WAIT for CE+DE or DE..>
------> I/O Interrupt(s)
Perform PRESENT
WRITE Operation:
TERMINAL SERVICE MACHINE CP Logical Dev
<------ Perform Write
if CC^0 then test and re-drive
<..WAIT for CE+DE or DE..>
------> I/O Interrupt(s)
<...WAIT...>
11.6 Program Flow (Recovery after NORMAL/TEST toggle or Unit Exception)
WRITE Operation:
TERMINAL SERVICE MACHINE CP Logical Dev
NORMAL/TEST toggle ------> Dialed device is
"dropped"
<------ Perform Write
if CC^0 then test and re-drive
<..WAIT for DE..>
Dial Command ------> I/O Interrupt(s)
<....DE....>
Resume Logic with last
active session displayed
11.7 Updating of non-displayed session
TERMINAL SERVICE MACHINE CP Logical Dev
Facility
Non-displayed session
External Interrupt <----- LogDev Fac
Perform ACCEPT data. <----- LogDev Fac
If number of msgs queued
is > max, and msg will not
overrun storage buffer then
Update stored buffer
with ACCEPTed data.
<...Continue...>
Else purge msg queue and
Update stored buffer
with ACCEPTed data.
<...Continue...>
Toggle Key ------> I/O Interrupt
AID 'xx'
<-----> Read Buffer
Store session buffer.
Set up for next session.
If previous session exist
Goto RESTSESS.
Perform DIAG 8C.
Perform INITIATE -----> LogDev Fac
Update dialed device
matrix.
Goto NEWSESS.
RESTSESS:
Restore next seq session
Previous Display <------ Write to Dialed device
any queued messages.
<...WAIT...>
OPERATION: Start: execute LDEVMLTS
Stop: Enter: LDEVTERM
Dial into service machine running LDEVMLTS
12.1 Define Virtual Machine for MLTS
This assumes that the LDEVMLTS components are on the 19F disk.
Console for MLTS Service Machine must be at address 01F or 009.
USER LVM1 ANYPASS 4M 8M G 12100941
ACCOUNT 702 LVM1 12100941
IPL CMS PARM AUTOCR 12100941
SHARE REL 1000
CONSOLE 009 3270 T 12100941
SPOOL 00C 3505 * 12100941
SPOOL 00D 3525 12100941
SPOOL 00E 3203 A 12100941
LINK MAINT 190 190 RR 12100941
LINK MAINT 19D 19D RR 12100941
LINK MAINT 19E 19E RR 12100941
LINK MAINT 19F 19F RR 12100941
MDISK 191 3375 81 1 VMSRES MR READ 12100941
12.11 Performance Recommendations
Lock MLTS Service Machine pages 0 and 20 thru 2A.
Set SHARE so that MLTS receives service at a level higher
than logical user sessions.
12.2 Service Machine PROFILE EXEC
This assumes that the LDEVMLTS components are on the 19F disk.
/* Profile Exec for LDEVMLTS Service Machine */
TRACE ALL
'SET RDYMSG SMSG'
'SET EMSG ON'
'CP SET RUN ON'
'CP AUTOREAD OFF'
'CP TERM HILIGHT ON'
'CP SCREEN VMOUT RED NONE INAREA YELLOW NONE'
'CP SCREEN STATAREA PINK NONE CPOUT TUR NONE INREDISP WHIT NONE'
'CP SP 00C CL *'
'CP SP PRT * '
'ACC 19F W'
'CP SET PF12 RETRIEVE'
'CP SET PF24 RETRIEVE'
'EXECIO 1 CP (STRING QUERY ' USERID()
parse pull . . where .
if where = "DSC" then
do
queue 'LDEVMLTS'
end
EXIT 0
12.3 Invocation EXEC
/* Last Update: 01-13-90 */
TRACE off
'CP SET EMSG OFF'
'CP SET MSG OFF'
'CP SET IMSG OFF'
n = 0
ADDRESS COMMAND 'EXECIO * CP (STRING Q PF '
DO WHILE (QUEUED() > 0)
n = n + 1
PARSE PULL pfk.n a1.n a2.n a3.n a4.n a5.n a6.n a7.n a8.n .
END
'CP TERM BRKKEY PA1'
DESBUF
'CP SET RUN OFF'
'CP SET PF12 RET'
'vmfclear'
LDEVMLTS
'CP SET RUN ON'
DO i = 1 to n
'EXECIO 0 CP (STRING SET 'pfk.i a1.i a2.i a3.i a4.i a5.i a6.i a7.i a8.i
END
'CP SET EMSG ON'
'CP SET MSG ON'
'CP SET IMSG ON'
'CP TERM HILIGHT ON'
RETURN 0
12.4 Operational Commands for the MLTS Service Machine
The Service Machine console must be defined at either x'0009' or x'00
The logical device ports that will be defined by LDEVMLTS will be:
x'0010'
x'0011'
x'0012'
x'0013'
x'0014'
x'0015'
x'0016'
x'0017'
x'0018'
x'0019'
x'001A'
x'001B'
x'001C'
x'001D'
x'001E'
x'001F'
Automatic Approach:
Build one or more service virtual machines based on supplied example.
Create a PROFILE EXEC based upon supplied sample. This will start .
the MLTS service facility if autologged and disconnected.
Have autolog performed by your AUTOLOG1 machine or done manually. .
Manual Approach:
Build one or more service virtual machines based on supplied example.
Logon to MLTS Service machine.
Start: execute LDEVMLTS
(The time and version number will display)
then enter #CP DISCONNECT
Stop: Logon to MLTS Service Machine
#CP BEGIN
Enter: LDEVTERM
Dump Trace Data: Logon to MLTS Service Machine
#CP BEGIN
Enter: LDEVTRAC
1 Recovery
In event of 'NORMAL/TEST' toggle, and dialed device is dropped from
the service machine:
DIAL the MLTS Service Machine (ie LVM1)
(last displayed session should be re-established)
In event of 'hang' condition or other failure then:
LOGON to the MLTS Service Machine (ie LVM1)
#CP SYSTEM CLEAR
#CP SYSTEM RESET
#CP IPL CMS
(To restart see above MANUAL APPROACH)
Exception event messages will be logged on the MLTS Service Machine
console when in "CONNECT" mode. No messages are logged when 'DSC'
1 For the Dialed user terminals
Dial the MLTS_Service_Machine.
CP will post the 'DIALED TO XXXXXXX as VDEV' message.
Hit Enter, the CTS Logo will be displayed. Logical Device terminal
characteristics as determined by the Diagnose X'8C' are posted at the
upper right of the logo screen.
The virtual dialing address is assigned and posted at the upper righ
The date and time of the last CMS IPL performed on the Service Machi
appear just above the logo.
At this time the user
is prompted to select the number of concurrent logical sessions they
desire (2-8, default is 2) and the user may select the PA or PF key
that is to be used as the "session toggle" hot key. This key will
be used to jump to the next session and cannot be used by the under-
lying application. The default PA2 becomes armed to toggle between
two sessions if the user hits the ENTER key with no selectables.
Constraint: To select a number of sessions greater than the default
the user MUST use either a PF key as the 'toggle' key or accept the
PA2 default as the 'toggle' key. Explicit choosing of PA1, PA2 or
PA3 as the 'toggle' key will restrict you to the DEFAULT number of
sessions.
Also at this time the user is prompted to optionally select the PF key
that is to be used as the session "backward" toggle key. This key will
be used to jump to the previous session and cannot be used by the under-
lying application. No default is armed in the event of no selection
Constraint: Backward toggle must be a PF Key or PA Key.
The acceptable entries are PFxx ,where xx is 01 thru 24.
PAy ,where y is 1 thru 3.
Hit Enter, the VM Logo will appear. The first logical session has
been established and further sessions can be created using the
"session toggle" keys.
Hit session toggle key to establish next multiple logical session.
A VM Logo will appear for each new logical session.
Each session toggle will save the current displayed session and
sequence to the next session in round-robin fashion. (1-2-3-...-1)
or backward toggling (-4-3-2-1-...-4).
The current display and up to 32 queued update messages are saved.
1Termination of any one Logical Sessions:
(1) If logged on to a virtual machine:
Disconnect or Logoff
You will receive normal CP messages
Upon enter the VM Logo will appear.
(2) If dialed in to a virtual machine:
Use normal disconnect sequence as you would without MLTS.
(such as VTAM, PASSTHRU, VSE CICS)
Upon CP RESET done by above applications your keyboard may lock.
Press RESET key followed by Enter
If NOT LOCKED then just press Enter a second time
Upon enter the VM Logo will appear.
Termination of all Logical Sessions and detachment from Service Machine
First Logoff or Disconnect from each logical session leaving the
VM Logo displayed on each.
On ANY session displaying the VM LOGO, from field:
'COMMAND ===> ldevexit'
-OR-
The screen following an ENTER stroke from the VM LOGO:
Enter: This will terminate all logical sessions between
'LDEVEXIT' this port and CP, then the MLTS service machine will
or perform a CP RESET of this DIALED port.
'ldevexit' This commands can be entered at the lower left-hand
corner of the cleared VM Logo display surface.
Enter: This will preserve the logical sessions between
'LDEVDISC' this port and CP, then the MLTS service machine will
or perform a CP RESET of this DIALED port.
'ldevdisc' This commands can be entered at the lower left-hand
corner of the cleared VM Logo display surface.
Emergency Termination from Multiple Logical Device Service Facility.
In the event of an unrecoverable 'hang' condition in which the
MLTS service machine becomes disabled for interrupts (or just plain
sick) then:
Use the NORMAL/TEST hardware switch of your terminal to DROP
all sessions with the MLTS.
The logical sessions may enter FORCED / DISCONNECT state.
or the equivalent state you would experience if one performed a
NORMAL/TEST against any logged/dialed session.
Program Product Exceptions
* * * Known Problem Areas and Constraints * * *
--If any of the logical session screens are updated while they are in
the MLTS saved buffers, ..AND..the number of queued messages has
exceeded the limit,..OR..the queued messages will overrun the queued
message buffers, THEN only the most recent 3270 datastream is
preserved for re-display when you hot-key back to that session.
--An application that sits behind the Logical Session (such as you are
dialed into CICS) will not be able to perform a screen read operation
to one of the logical screens if that screen is not currently on the
physical terminal. In most applications this is not a problem since
the request for a read is ACCEPTED by the MLTS Service Machine in the
form of a READ I/O data stream command which will be queued until the
user toggles to that session.
--Extended field attributing and some extended color is not preserved when
saving the contents of the display surface during 'hot-key' jumping.
Field attributes and extended color is usually restored upon the next
write to the terminal by the application.
--Lost logical device can occur during disconnect, reset or logoff of a
MLTA session who has another MLTA session as a secondary console.
The lost session will not accept I/O since it is marked severed in CP
and active in the MLTA logical device tables.
--Disc logical device can occur during shutdown processing of a second
level VM Guest. The CP console for the VM Guest posts the normal
warm start saved and RRR.III.NNGG messages, then first level CP issues
a CP TERMINATE which causes the MLTS to detach that logical session.
The recovery action is to manually detach the logical device from
the MLTS machine (XA only).
--If an underlying application driving a session places the logical
terminal in a inhibit mode, and that logical session becomes the
displayed physical session, then the inhibit is preserved and honored
This will prevent toggling until the inhibit is cleared using 3270
conventions, such as Erase/Write from the underlying application.
15.0 Messages that will appear on MLTS service console
Start Message:
YY/MM/DD L Enter 'LDEVTERM' to terminate
Stop Message:
Termination Complete, returning to CMS
Unknown Request Message:
Undetermined Request, ...CONTINUING...
Disconnection Message:
DISCONNECT from logical sessions
Exit Message:
EXIT from logical sessions
Logical Device Operation Condition Code / Logical Device
Operation Exceptions Return Code pair Address
------------------------ ---------------- --------------
INITIATE CC RC cccc
REINIT (Re-Initiate) CC RC cccc
ACCEPT CC RC cccc
PRESENT CC RC cccc
TERMINAT (MLT Terminate) CC RC cccc
CPTERMIN (CP Terminate) CC RC cccc
**See description of codes in IBM Logical Device Facility manual.
MLTS Device I/O
Operation Exceptions Return Code Address
------------------------ ---------------- --------------
SCRERR (Screen Error) RC 01F or 009
0A = Device Not Operational
0B = Channel Path Problems
0D = Unit Exception
Logical Device Support Facility External Interrupt Reason Codes
IRCODE=0 External Interrupt Return Code from Diagnose 7C
IRCODE=1 External Interrupt Return Code from Diagnose 7C
IRCODE=2 External Interrupt Return Code from Diagnose 7C
IRCODE=3 External Interrupt Return Code from Diagnose 7C
IRCODE=4 External Interrupt Return Code from Diagnose 7C
IRCODE=5 External Interrupt Return Code from Diagnose 7C
IRCODE>5 External Interrupt Return Code from Diagnose 7C
CPTERM ? Terminate Failed because logical device not in matrix.
UNEX INT Unexpected Interrupt occurred
NO LDEV No logical device listed
NO SLOT Logical device matrix slot position invalid.
PFUNPURG Last PRESENT function has been purged.
TRANSERR CP posted error in transmission.
Disclaimer
In no event will Licensor or its representatives be liable to the
Licensee or any other party for any loss, including time, money,
good will and consequential damages, which may arise from the use,
operation, modification or interpretation of the Licensed Program by
the Licensee. CTS does not warrant that the functions contained in
the program will meet the customer's requirements or will operate in
combinations which may be selected for user by the customer, or that
the operations of the program will be uninterrupted or error free, or
that all program defects will be corrected.