Virtel Connectivity Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 231 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Virtel Connectivity Guide
Release 4.58
Syspertec Communications
Nov 12, 2018
TABLE OF CONTENTS:
1 Conguring Virtel 3
1.1 Accessing the conguration manager ................................ 3
1.1.1 Virtel 3270 Application ................................... 3
1.1.2 THe Web Portal (3270) .................................. 5
1.1.3 The Web Portal (GUI) ................................... 6
1.2 Congurable Elements ........................................ 7
1.2.1 Unloading Congurable Elements ............................. 9
1.2.2 Line Element ........................................ 10
1.2.3 Entry Point Element .................................... 11
1.2.4 Transaction Element .................................... 12
1.2.5 Terminal Elements ..................................... 13
1.2.6 Adding new congurable elements ............................. 17
1.3 Administration ............................................ 21
1.3.1 Conguration Menu .................................... 22
1.3.2 Sub-Application Menu ................................... 23
1.3.3 Screen Navigation ...................................... 23
2 Lines 25
2.1 Introduction ............................................. 25
2.2 Line Management Sub-Applications ................................ 25
2.2.1 Security ........................................... 25
2.2.2 Summary Display ...................................... 25
2.2.3 Detail Display ........................................ 27
2.2.4 Parameters ......................................... 27
2.3 Line Overview Sub-Application ................................... 32
2.4 HTTP Inbound line ......................................... 33
2.4.1 Terminal Denitions .................................... 34
2.4.2 VTAM Terminal Denitions ................................ 37
2.4.3 CICS Denitions ...................................... 37
2.5 HTTP Outbound line ........................................ 38
2.5.1 Parameters ......................................... 39
2.6 HTTP Outbound SMTP line .................................... 39
2.6.1 Parameters ......................................... 40
2.6.2 Terminal Denitions .................................... 41
2.6.3 VTAM Terminal Denitions ................................ 42
2.6.4 CICS Denitions ...................................... 42
2.7 IMS Connect line .......................................... 43
2.7.1 Parameters ......................................... 43
2.7.2 Terminals Denitions .................................... 44
2.7.3 Entry Point ......................................... 44
i
2.7.4 Transactions ......................................... 45
2.7.5 Scenarios ........................................... 46
2.7.6 Message format ....................................... 47
2.8 MQ line ................................................ 48
2.8.1 Parameters ......................................... 48
2.8.2 Terminal Parameters .................................... 49
2.9 Batch line .............................................. 51
2.9.1 Parameters ......................................... 51
2.9.2 Terminal Denitions .................................... 52
2.10 Native TCP/IP Gateway line .................................... 53
2.10.1 Parameters ......................................... 53
2.10.2 Line Terminals ....................................... 54
2.10.3 Terminal Parameters .................................... 54
2.10.4 Relay Pool .......................................... 55
2.10.5 VTAM terminals denitions ................................ 55
2.10.6 CICS Denitions ...................................... 55
2.10.7 Message format ....................................... 56
2.11 VIRPASS TCP line (VIRKIX) ................................... 57
2.11.1 Parameters ......................................... 57
2.11.2 Terminal Denitions .................................... 58
2.12 VIRPASS TCP line (VIRNT) ................................... 59
2.12.1 Parameters ......................................... 59
2.12.2 Terminal Denitions .................................... 60
2.13 VIRPASS XM line (VIRKIX) ................................... 62
2.13.1 Parameters ......................................... 62
2.13.2 Terminal Denitions .................................... 63
2.14 X25 XOT line ............................................ 65
2.14.1 Parameters ......................................... 65
2.14.2 Terminal Denitions .................................... 66
2.14.3 VTAM Terminal Denition ................................ 67
2.15 X25 VIRPESIT line ......................................... 68
2.15.1 Parameters ......................................... 68
2.15.2 Terminal Denitions .................................... 69
2.16 X25 VIRNEOX line ......................................... 70
2.16.1 Parameters ......................................... 70
2.16.2 Terminal Denitions .................................... 71
2.17 X25 GATE Non Fast-Connect (NFC) line ............................. 72
2.17.1 Parameters ......................................... 72
2.17.2 Terminal Denitions .................................... 73
2.17.3 VTAM Terminal Denitions ................................ 73
2.17.4 NCP Parameters ...................................... 74
2.17.5 NPSI Parameters ...................................... 74
2.17.6 Routing on incoming calls ................................. 75
2.18 X25 GATE Fast-Connect (FastC) line ............................... 77
2.18.1 Parameters ......................................... 77
2.18.2 Terminal Denitions .................................... 78
2.18.3 VTAM Terminal Denitions ................................ 78
2.18.4 NCP/NPSI Denitions ................................... 79
2.18.5 Sharing of FastC lines ................................... 79
2.19 X25 AntiGATE line ......................................... 81
2.19.1 Parameters ......................................... 81
2.19.2 Terminal Denitions .................................... 82
2.19.3 VTAM Terminal Denitions ................................ 82
2.20 X25 Anti Fast Connect (FastC) line ................................ 84
ii
2.20.1 Parameters ......................................... 84
2.20.2 Terminal Denitions .................................... 85
2.20.3 VTAM Terminal Denitions ................................ 85
2.21 X25 AntiPCNE line ......................................... 86
2.21.1 Parameters ......................................... 86
2.21.2 Terminal Denitions .................................... 87
2.21.3 VTAM Terminal Denitions ................................ 91
2.21.4 Add or changing AntiPCNE LU names .......................... 91
2.21.5 Support of X25 non GATE terminals ........................... 92
2.21.6 VTAM denitions for X25 non GATE terminals ..................... 92
2.21.7 NCP/NPSI parameters for X25 non GATE terminals .................. 93
3 Virtel Rules 95
3.1 Introduction ............................................. 95
3.1.1 Summary Display ...................................... 95
3.1.2 Detail Display ........................................ 96
3.1.3 Parameters ......................................... 97
4 Terminals 101
4.1 Introduction .............................................101
4.1.1 Terminal Management Sub-Application ..........................101
4.1.2 Security ...........................................101
4.1.3 Summary Display ......................................101
4.1.4 Detail Display ........................................103
4.1.5 Parameters .........................................103
5 Entry Points 107
5.1 Introduction .............................................107
5.1.1 Entry Point Management Sub-Application ........................107
5.1.2 Security ...........................................107
5.1.3 Selecting an Entry Point ..................................107
5.1.4 Summary Display ......................................108
5.1.5 Transaction Display ....................................109
5.1.6 Detail Display ........................................110
5.1.7 Parameters .........................................110
5.1.8 Signon Programs ......................................112
5.1.9 Menu Programs .......................................112
6 Transactions 115
6.1 Introduction .............................................115
6.1.1 Summary Display ......................................115
6.1.2 Detail Display ........................................116
6.1.3 Parameters .........................................117
7 Connection / Disconnection Scripts 123
7.1 Script Programming Language ...................................123
7.1.1 Transmission and lter commands ............................123
7.1.2 System variables ......................................124
7.1.3 Orders ............................................124
7.1.4 Method of operation ....................................125
7.2 Script Examples ...........................................126
7.2.1 Connect to CICS (no sign-on) with automatic start of a transaction .........126
7.2.2 Connect to CICS and start transaction CESN with transmission of credentials . . . . 127
7.2.3 Connect to CICS VSE with ICCF sign-on and start transaction CEMT . . . . . . . 127
7.2.4 Connect to TSO with USER and PASSWORD and await start of ISPF . . . . . . . 128
iii
7.2.5 Connect to CICS and navigate a user applicaction ...................128
7.2.6 Service Transaction .....................................128
8 External Servers 131
8.1 Introduction .............................................131
8.1.1 External Server Management Sub-Application ......................131
8.1.2 Security ...........................................131
8.1.3 Summary Display ......................................131
8.1.4 Detail Display ........................................133
8.1.5 Parameters .........................................133
9 Connection Modes 137
9.1 WELCOME mode ..........................................137
9.2 RELAY mode ............................................137
9.3 Terminal Connection Types .....................................137
9.3.1 Explicit xed entries ....................................138
9.3.2 Physical Terminal Pools ..................................139
9.3.3 Dynamic Terminal Pools ..................................139
9.3.4 Non-Dynamic Terminal Pools ...............................140
9.3.5 Terminal Pool Denition Examples ............................140
9.3.6 Terminal Pool Selection ..................................141
9.4 Terminal Connection Examples ...................................143
9.4.1 3270 terminal in WELCOME mode ............................143
9.4.2 3270 terminal in RELAY mode ..............................143
9.4.3 Asynchronous terminal on an X25 or XOT line .....................144
9.4.4 Logical terminals ......................................144
10 Controlling LUNAMEs 147
10.1 Introduction .............................................147
10.2 LU Nailing By URL .........................................147
10.2.1 UserData example using a work station name ......................148
10.2.2 UserData example using a LU Name ...........................150
10.2.3 ForceLUNAME Example ..................................151
10.3 LU Nailing by cookie ........................................154
10.4 LU Nailing by IP address ......................................155
10.5 Comparison Table ..........................................157
11 AT-TLS Secure Session 159
11.1 Introduction .............................................159
11.2 Installation ..............................................159
11.2.1 Install Policy Agent procedure ...............................159
11.2.2 Create the Policy Agent conguration le ........................159
11.2.3 Allow the Policy Agent to run during TCP/IP initialization ..............160
11.2.4 Create the server certicate ................................160
11.2.5 Add the certicate to the keyring .............................160
11.2.6 Allow VIRTEL to access its own certicate .......................160
11.2.7 Activate AT-TLS ......................................160
11.3 Operations ..............................................161
11.3.1 Starting the Policy Agent .................................161
11.3.2 Altering the Policy Agent conguration .........................161
11.3.3 Logon to VIRTEL using secure session ..........................161
11.4 Problem determination .......................................162
11.4.1 Policy Agent log le ....................................162
11.4.2 Common error messages ..................................162
11.4.3 Verifying AT-TLS is active .................................163
iv
11.5 The Cipher suites ..........................................164
11.6 Client certicates ..........................................164
11.7 Resources ...............................................165
11.7.1 IBM Manuals ........................................165
11.7.2 Virtel Material .......................................165
12 SSO, PassTickets and Proxy Servers 167
12.1 Introduction .............................................167
12.2 Adding headers to the HTTP request ...............................169
12.3 RACF Passtickets ..........................................171
12.3.1 Dene Pass Ticket RACF proles .............................171
12.3.2 RACF Proles related to Virtel and Pass Tickets ....................172
12.4 Virtel Requirements .........................................175
12.4.1 Transaction requirements .................................175
12.4.2 Identication Scenario ...................................176
12.4.3 TCT Considerations ....................................177
12.4.4 Line Rules ..........................................178
12.5 Common Errors ...........................................181
12.6 Related material ...........................................182
13 Running multiple instances of Virtel 183
13.1 Introduction .............................................183
13.1.1 VIRTEL TCT Settings ...................................184
13.1.2 SYSPLEX denitions ....................................184
13.1.3 Workload balancing in a SYSPLEX environment ....................186
13.1.4 Sharing the ARBO and other VSAM les ........................187
13.1.5 READ ONLY Restrictions .................................187
13.1.6 Virtel naming conventions .................................188
13.1.7 TCT denition .......................................188
13.2 Using a Distributed VIPA to load balance .............................191
13.2.1 Session Anity .......................................191
13.3 Using an Apache Proxy to load balance ..............................192
14 VIRPLEX 195
14.1 Setting up a Virplex .........................................196
14.2 TCT denitions ...........................................196
14.2.1 TCT for ‘READER’ tasks. .................................196
14.2.2 TCT for ‘WRITER’ task ..................................197
14.3 ARBO denitions ..........................................197
15 Protecting business assets with Virtel Rules 211
15.1 Introduction .............................................211
15.2 Virtel Setup .............................................213
15.2.1 Virtel Rules .........................................213
15.2.2 Default Rule Template ...................................214
16 Appendix 217
16.1 Trademarks ..............................................217
v
vi
Virtel Connectivity Guide, Release 4.58
VIRTEL Connectivity Reference
Warning: This book is currently under construction. This is a draft version!
Version : 4.58
Release Date : 01 Jul 2017 Publication Date : 01/07/2017
Syspertec Communication
196, Bureaux de la Colline 92213 Saint-Cloud Cedex Tél. : +33 (0) 1 46 02 60 42
www.syspertec.com
Note: Reproduction, transfer, distribution, or storage, in any form, of all or any part of the contents of
this document, except by prior authorization of SysperTec Communication, is prohibited.
Every possible eort has been made by SysperTec Communication to ensure that this document is complete
and relevant. In no case can SysperTec Communication be held responsible for any damages, direct or
indirect, caused by errors or omissions in this document.
As SysperTec Communication uses a continuous development methodology; the information contained in
this document may be subject to change without notice. Nothing in this document should be construed in
any manner as conferring a right to use, in whole or in part, the products or trademarks quoted herein.
“SysperTec Communication” and “VIRTEL” are registered trademarks. Names of other products and com-
panies mentioned in this document may be trademarks or registered trademarks of their respective owners.
TABLE OF CONTENTS: 1
Virtel Connectivity Guide, Release 4.58
2 TABLE OF CONTENTS:
CHAPTER
ONE
CONFIGURING VIRTEL
1.1 Accessing the conguration manager
The conguration manager can be access in one of three ways.
1.1.1 Virtel 3270 Application
1. By logging onto the Virtel application as dened by the APPLNAME in the TCT or at start up in the
Virtel JCL parameters.
LOGON APPLID=VIRTEL
The following main menu will appear:-
3
Virtel Connectivity Guide, Release 4.58
Enter you security credentials and the primary menu will appear.
Enter F1 to enter the conguration menu of the conguration manager.
4 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
1.1.2 THe Web Portal (3270)
2. By accessing Virtel through the administration port 41001.
http://192.168.170.33:41001/
The following page will be displayed:-
Click the Admin (3270) link and the conguration menu will appear.
1.1. Accessing the conguration manager 5
Virtel Connectivity Guide, Release 4.58
1.1.3 The Web Portal (GUI)
3. Accessing Virtel as in the Web Portal (3270) but instead of clicking Admin (3270) click Admin (GUI).
You will be presented with a GUI view of the 3270 conguration screens.
6 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
1.2 Congurable Elements
The VIRTEL conguration is stored in a VSAM le called the “ARBO le” (VIRARBO). The ARBO le
contains various types of elements, which are described in this chapter:
• Lines, which represent connections between VIRTEL and other network entities
• Rules, which are applied to incoming calls in order to establish the appropriate entry point for the call
• Terminals, which represent the virtual circuits through which calls ow between VIRTEL and its
partners
• Entry points, which dene how the call is processed by VIRTEL and contain a list of transactions
available to the incoming call
• Transactions, which dene VTAM applications or external servers which process incoming calls
• External servers, which dene the connection parameters used by VIRTEL to connect outgoing calls
to other network entities
1.2. Congurable Elements 7
Virtel Connectivity Guide, Release 4.58
Congurable elements of Virtel
The diagram above describes the data ow between a TSO user accessing TSO on the mainframe. To support
this session various Virtel congurable elements, which are maintained in the ARBO le, are used. The Virtel
line denition represents an open port in TCP/IP which is the target of the browser’s URL. The Virtel line
is associated with a Virtel Entry point which in turn is associated with a list of Virtel transactions. One of
these transactions is a VTAM application denition representing TSO. The incoming URL determines the
transaction to associate with this session call. In this example the transaction TSO has been identied in
the URL string as a HTTP parameter. When the Virtel engine processes the incoming call it will establish
a SNA session with the TSO VTAM application. From the TSO VTAM application perspective it will be as
8 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
if a user had connected using a standard LU2 type terminal (3270). Virtel will convert datastreams between
3270 and HTML in support of the underlying session between the browser and TSO. This conversion process
will use several Virtel terminal denitions; 1 or more to represent the browser and another to represent the
VTAM interface with TSO. By convention “LOC” terminals reect units of work in supporting the browser
and “VTA” terminals represent the interface to the VTAM applications. Virtel terminal denitions are
associated with a Virtel line.
1.2.1 Unloading Congurable Elements
The Virtel program VIRCONF can be used to LOAD or UNLOAD the ARBO VSAM le which contains
the congurable elements. The default statements that are used to build the initial ARBO VSAM le are
contained in the CNTL library as member ARBOLOAD. This member contains every statement that could
potentially be used when dening the Virtel ARBO VSAM le, including optional statements which may
not be applicable. To unload the default ARBO VSAM le run the following JCL:-
//VIRARBOU JOB 1,ARBOUNLD,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//*
//* THIS JOB UNLOADS AN ARBO FILE
//*
// SET LOAD=yourqual.VIRTnnn.LOADLIB
// SET ARBO=yourqual.VIRTnnn.ARBO
//*
//UNLOAD EXEC PGM=VIRCONF,PARM=UNLOAD
//STEPLIB DD DSN=&LOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//VIRARBO DD DSN=&ARBO,DISP=SHR,AMP=('RMODE31=NONE')
//SYSPUNCH DD DSN=&SYSUID..VIRCONF.SYSIN,DISP=(,CATLG),
// UNIT=SYSDA,VOL=SER=??????,SPACE=(TRK,(5,1)),
// DCB=(RECFM=FB,LRECL=80,BLKSIZE=6080)
The ARBO UNLOAD Job
The output le contains all the default denitions that make up the congurable Virtel elements. These
denitions can be used as a template for building new congurable elements such as lines, entry points,
transactions, etc. See the VIRCONF utility section in the Virtel Installation Guide for further information
on the VIRCONF utility and maintaining the VSAM ARBO le.
1.2. Congurable Elements 9
Virtel Connectivity Guide, Release 4.58
1.2.2 Line Element
The Line element is the main control element in the denition hierarchy. When Virtel receives a call in from
a user, via their browser, it is targeted towards a particular port which is associated with a Line element.
The Line element points to the default entry point and also identies the listening port. By default, Virtel
delivers two HTTP line elements in its default conguration. Line W-HTTP associated with port 41001 and
Line C-HTTP associated with port 41002. Line W-HTTP(41001) is usually associated with administration
functions and should be secured for administration use only. Line C-HTTP(41002) is an example of a line
for for client applications. It is not advisable to use 41001 as your client port. USe 41002 or set-up another
line using 41002 as a template, for example 41003.
Line Detail Denition
It is also dened in the Arbo Conguration statements:-
LINE ID=C-HTTP, -
NAME=HTTP-CLI, -
LOCADDR=:41002,-
DESC='HTTP line (entry point CLIWHOST)',-
TERMINAL=CL, -
ENTRY=CLIWHOST, -
TYPE=TCP1, -
INOUT=1,-
PROTOCOL=VIRHTTP, -
TIMEOUT=0000,-
ACTION=0,-
WINSZ=0000,-
PKTSZ=0000,-
RETRY=0010
The same information is reected in both. The ARBO denitions are used to build the ARBO VSAM le
which the Virtel Sub Applications access to display, modify and delete conguration elements. Another key
item in the line denition is the TERMINAL prex. This prex is used to associate a line with the terminal
denitions. In the example above the prex of CL means that this line will only use terminal beginning
10 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
“CL”.
1.2.3 Entry Point Element
The Entry point element is associated with a group of transactions. Transactions are the interface to external
components like VTAM applications (CICS, TSO, IMS etc.) or external servers. Transactions are also used
to dene internal Virtel tasks and conguration elements like directory entries, upload programs, menu
programs, signon programs. A line can be associated with any entry point dened within the conguration.
Every line must have a default entry point. Virtel Rule denitions can be used to assign a dierent Entry
point to a call in request based upon a range of criteria - incoming IP Address, Work Station Name, Userid
etc.
Entry Point Denition
It can also dened with the Arbo Conguration statements:-
ENTRY ID=CLIWHOST, -
DESC='HTTP entry point (CLIENT application)',-
TRANSACT=CLI, -
TIMEOUT=0720,-
ACTION=0,-
EMUL=HTML, -
SIGNON=VIR0020H, -
MENU=VIR0021A, -
IDENT=SCENLOGM, -
EXTCOLOR=E
The salient point in the Entry Point element is the TRANSACT prex. This associates transactions with a
particular Entry point. In the sample above transactions that begin with CLI will be associated with entry
point CLIWHOST which is the default entry point for line C-HTTP(41002). An example of using an Entry
point is that you might want to associate productions users with line 41004 and other users with line 41005.
In this example you would dene two new lines, set default entry points PRODHOST and USERHOST.
In those entry point denitions the prex for production transactions would PRD and for user transactions
1.2. Congurable Elements 11
Virtel Connectivity Guide, Release 4.58
USR.
1.2.4 Transaction Element
Transactions dene the programs that Virtel will run in order to support a session requirement. Transactions
are normally identied within the incoming URL. For example the following URL requests that Virtel starts
a Virtel transaction called CICS:-
http://192.168.170.33:41002/w2h/WEB2AJAX.htm+Cics
When the Virtel Engine receives this call-in it directs to line C-HTTP(41002) and established a session
with the user’s browser. Session initiation begins with the downloading of various Virtel web elements such
as templates, JavasSrcipt and CSS pages. The line will invoke a transaction called CICS which will be
associated with the entry point dened for this call-in. This normally would be a transaction associated
with the default entry point CLIWHOST. However, Virtel Rules may well associate a dierent entry point
depending on call-in criteria. The transaction CICS is an external name, the Virtel Internal name for this
transactions is CLI-10. It is the internal name that is related to the transaction prex dened in the Entry
Point.
Transaction Denition
It can also dened with the Arbo Conguration statements:-
TRANSACT ID=CLI-10,-
NAME='Cics',-
DESC='Logon to CICS',-
APPL=SPCICST, -
TYPE=1,-
TERMINAL=CLVTA, -
STARTUP=1,-
SECURITY=1
The salient points here are the internal name or ID, CLI-10 which ties up with the Entry Point transaction
12 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
prex of transactions beginning “CLI”, the external name, “CICS” relates to the transaction name identied
in the call-in URL. The APPL keyword identies a name that will be used depending on the transaction type.
The transaction type for this particular transaction denition is a VTAM transaction, TYPE=1. Virtel will
attempt to logon to VTAM application identied by the VTAM APPL name SPCICST. The nal point is
the terminal prex which identies what Virtel terminals should be used to support this connection. In this
instance the terminals must be prexed with the characters “CLVTA”.
1.2.5 Terminal Elements
Terminal elements are used to support units of work within Virtel such as running a program, transmitting
data to a browser, representing a VTAM LU to a VTAM APPLICATION. These are just a few examples.
Terminal elements are dened to Virtel as either dynamic, static or pool. The following Summary Display
lists the terminals delivered in the default installation.
Terminal Denitions
The terminal name is used to associate terminals with lines and transactions. In the example for
the line C-HTTP(41002) we had a terminal prex of CL. So terminals CLLOC000-CLLOC079 and
CLVTA000-CLVTA079 will be associated with this line. Our Transaction CLI-10 requires a terminal whose
prex is CLVTA. CL terminals are allocated top down, meaning that the terminal allocated to the trans-
action will be the highest CLVTA079. The display shows that CLLOC000-CLLOC079 are static terminal
entries. CLVTA000-CLVTA079 are dynamic entries and point to a pool called *W2HPOOL. Whenever a
terminal is required from a pool the terminal name returned will be the rst free terminal within the pool.
Dening pool terminals is through the use of the Pool name in the terminal denition. So in the pool
*W2HPOOL terminals whose name begin with W2HTP000-WH2HTP079 have been dened. So, when the
TSO transaction is kicked o Virtel will request a terminal whose name begins CLVTA, CLVTA079 will be
assigned. This will grab the rst available terminal in the *W2HPOOL as that is where CLVTA points to.
The rst available terminal in the pool will be W2HTP000. Virtel always works from the lowest free name
entry when returning pool entries.
1.2. Congurable Elements 13
Virtel Connectivity Guide, Release 4.58
Terminal Pool denition
Terminal Denitions dened with Arbo conguration statements:-
TERMINAL ID=CLLOC000, Static Definition
DESC='HTTP terminals (no relay)',
TYPE=3,
COMPRESS=2,
INOUT=3,
STATS=26,
REPEAT=0050
TERMINAL ID=CLVTA000, Dynamic Definition
RELAY=\*W2HPOOL, <---- Use this pool
DESC='HTTP terminals (with relay)',
TYPE=3,
COMPRESS=2,
INOUT=3,
STATS=26,
REPEAT=0080
TERMINAL ID=W2HTP000, Pool definition
RELAY=REHVT000,
POOL=\*W2HPOOL, <---- Defines which pool
DESC='Relay pool for HTTP',
RELAY2=REHIM000,
TYPE=3,
COMPRESS=2,
INOUT=3,
STATS=26,
REPEAT=0080
In the case of logging onto CICS, the Virtel transaction will request a CLVTA terminal(CLVTA079) and
terminal WH2TP000 will be returned from *W2HPOOL. This terminal has an association with a relay name
represented by a VTAM terminal denition - in this case REHVT000. This relay name should be dened
14 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
to VTAM. Also, this terminal denition has a 2nd relay called REHIM000. Again, this is a VTAM APPL
denition which represents a SNA printer associated with the screen LU REHVT000. This name must also
be dened to VTAM. REHIM000 is a relay name associated with the static terminal denitions beginning
W2HIM000. In the logon to CICS we have three terminal names associated with the VTAM interface -
CLVTA079, W2HTP000(REHVT000) and W2HIM000(REHIM000).
Here are the VTAM denitions:-
VIRTAPPL VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
* Product : VIRTEL *
* Description : Main ACB for VIRTEL application *
* ------------------------------------------------------------------ *
APPLHOLT APPL EAS=160,AUTH=(ACQ,BLOCK,PASS,SPO),ACBNAME=APPLHOLT <----
,→VIRTEL ACB
* ------------------------------------------------------------------ *
* REHVTxxx : VTAM application relays for VIRTEL Web Access *
* ------------------------------------------------------------------ *
REHVT??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1 <----
,→Terminal Relay definitions
* ------------------------------------------------------------------ *
* REHIMxxx : Printer relays for VIRTEL Web Access terminals *
* ------------------------------------------------------------------ *
REHIM??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SCS,EAS=1 <---
,→Printer definitions SCS
REHIP??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=DSILGMOD,EAS=1 <---
,→Printer definitions 3270
1.2. Congurable Elements 15
Virtel Connectivity Guide, Release 4.58
Example of congurable Elements
16 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
1.2.6 Adding new congurable elements
Adding new congurable elements can be online, through the Virtel Portal (Port 41001), or via batch using
the VIRCONF util. The following is an example of adding a new interface to Virtel. The interface is line
E-HTTP(41003) which uses entry point EDSHOST. Entry point EDSHOST has the following transactions:-
EDS-00 Transaction to support the Entry Point. Must have an external name the same as the Entry Point.
In this case EDSHOST. Identies the default transaction. That being what transaction should be
initiated is none is specied in the URL.
EDS-03W Point to the w2h directory where all the Virtel web artifacts are maintained. In this case the
W2H directory.
EDS-03X Point to the directory that is associated with this line. This would contain customized web
elements such as a company image or logo. The directory is EDS-DIR which has a pathname of /eds.
EDS-04 Vtam transaction identifying SPCICST
EDS-90 Application menu transaction used as the default transaction and identied in the TIOA string in
transaction EDS-00
W2H-80S A transaction added to the W2H Entry point to support uploading web articfacts to the EDS-
DIR. When adding a new diorectory to Virtel you must also add a new upload transaction to the W2H
transaction group. The external name and logmsg of the transaction should identify the directory.
For example in this case name = upleds and logmsg = EDS-DIR. If you do not specify this “upload”
transaction the new directory will not appear in the administration portal display of in the directory
summary display.
Apart from the LINE, Entry Point and Transaction there is one other congurable element which must also
be added to support a new interface. This is the SUBDIR element. The SUBDIR element identies a new
directory.
1.2. Congurable Elements 17
Virtel Connectivity Guide, Release 4.58
//SPTHOLTV JOB 1,ARBOLOAD,CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//*--------------------------------------------------------------*
//* *
//* ARBO MIGRATION.UPDATE ARBO TO ADD NEW ELEMENTS *
//* *
//* Change Description Release *
//* Create directory for poc test V458 *
//* *
//*--------------------------------------------------------------*
//*
// SET LOAD=SPTHOLT.VIRT458.LOADLIB
// SET ARBO=SPTHOLT.VIRT458.ARBO
//*
//CONFIG EXEC PGM=VIRCONF,PARM='LOAD,NOREPL',REGION=2M
//STEPLIB DD DSN=&LOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//VIRARBO DD DSN=&ARBO,DISP=SHR
//SYSIN DD *
TERMINAL ID=EHLOC000, -
DESC='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
SUBDIR ID=EDS-DIR, -
DESC='EDS directory',-
DDNAME=HTMLTRSF, -
KEY=EDS-KEY, -
NAMELEN=0064,-
AUTHUP=X, -
AUTHDOWN=X, -
AUTHDEL=X
ENTRY ID=EDSHOST, -
DESC='HTTP entry point (EDS application)',-
TRANSACT=EDS, -
TIMEOUT=0720,-
ACTION=0,-
EMUL=HTML, -
SIGNON=VIR0020H, -
MENU=VIR0021A, -
IDENT=SCENLOGM, -
SCENDIR=SCE-DIR, -
EXTCOLOR=E
TRANSACT ID=EDS-00,-
NAME=EDSHOST, -
DESC='Default Directory',-
APPL=EDS-DIR, -
TYPE=4,-
TERMINAL=EHLOC, -
18 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
STARTUP=2,-
SECURITY=0,-
TIOASTA='/w2h/appmenu.htm+applist'
TRANSACT ID=EDS-03W, -
NAME='w2h',-
DESC='W2H toolkit directory (/w2h)',-
APPL=W2H-DIR, -
TYPE=4,-
STARTUP=2,-
SECURITY=0
TRANSACT ID=EDS-03X, -
NAME='eds',-
DESC='EDS directory (/eds)',-
APPL=EDS-DIR, -
TYPE=4,-
STARTUP=2,-
SECURITY=0
TRANSACT ID=EDS-04,-
NAME='CICS',-
DESC='CICS',-
APPL=SPCICST, -
TYPE=1,-
TERMINAL=EHVTA, -
STARTUP=1,-
SECURITY=0
TRANSACT ID=EDS-90,-
NAME='applist',-
DESC='List of applications for appmenu.htm',-
APPL=VIR0021S, -
TYPE=2,-
TERMINAL=EHLOC, -
STARTUP=2,-
SECURITY=1
TRANSACT ID=W2H-80S, -
NAME='upleds',-
DESC='Upload macros (EDS-DIR directory)',-
APPL=VIR0041C, -
TYPE=2,-
TERMINAL=DELOC, -
STARTUP=2,-
SECURITY=1,-
LOGMSG=EDS-DIR
LINE ID=E-HTTP, -
NAME=HTTP-EDS, -
LOCADDR=:41003,-
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
Conguration statements to add a new interface
1.2. Congurable Elements 19
Virtel Connectivity Guide, Release 4.58
After running the VIRCONF utility check to make sure that the condition code is zero and that all elements
have been added.
20 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
1.3 Administration
The VIRTEL system administrator uses a set of programs called sub-applications to display and update the
various elements in the VIRTEL conguration. The sub-applications are invoked via the Conguration Menu
or the Sub- Application Menu. The Conguration Menu, introduced in VIRTEL version 4.27, provides access
to the most commonly- used sub-applications required for VIRTEL Web Access and XOT. It is invoked from
the VIRTEL Multi-Session menu via a transaction which calls module VIR0022. The Sub-Application Menu,
invoked from the Conguration Menu, gives access to all of the sub-applications, including those rarely used
today.
If you log on to VIRTEL in 3270 mode using the default entry point (“PC”), the VIRTEL Multi-Session
menu oers the choice F1 – Admin to invoke the Conguration Menu.
The rst screen you will see is the Multi-Session menu:
The VIRTEL Multi-Session menu
Press [F1] to display the Conguration Menu:
1.3. Administration 21
Virtel Connectivity Guide, Release 4.58
1.3.1 Conguration Menu
The conguration Menu presents a list of sub applications which can be invoked to manage various Virtel
entities such as lines, terminals, entry points etc.
Conguration Menu
To invoke a sub-application, press one of the function keys shown in the menu (for example, F1 – Lines). To
exit from the Conguration Menu and return to the Multi-Session menu, press CLEAR.
From within the conguration Menu a further set of sub-applications can be accessible by pressing [PA2]
22 Chapter 1. Conguring Virtel
Virtel Connectivity Guide, Release 4.58
1.3.2 Sub-Application Menu
This menu presents a menu of additional sub-applications that can be used to manage Virtel.
Sub-Application Menu
To invoke a sub-application from this menu, press one of the function keys shown in the menu (for example,
F7 – Videotex Denitions). To exit from the Sub-Application Menu and return to the Conguration Menu,
press CLEAR or PA2.
1.3.3 Screen Navigation
The sub-applications have certain common operational characteristics:
• Most of the sub-applications start by displaying a list of the elements currently dened in the cong-
uration le.
• To scroll up or down the list, press [F7] or [F8].
• To nd an element in the list, overtype the name of the rst element displayed with the rst few
characters of the element name you are looking for, then press [ENTER].
• To display the detail screen for a particular element, place the cursor on the element name in the list
and press [F12].
• To alter the denition of an element, type the desired changes into the appropriate elds in the list
and press [F1]. VIRTEL recognizes the changes only when you press [F1]. If you change a transaction
you must also press [F1] on the entry point that the transaction belongs to.
• To delete an element, place the cursor on the element name in the list and press [F2]. Then press [F2]
again to conrm the deletion.
1.3. Administration 23
Virtel Connectivity Guide, Release 4.58
• To create a new element, place the cursor on a part of the screen outside the list, and press [F12]. A
detail screen will be displayed with all elds blank. Fill in the elds and press [ENTER].
• To copy an existing element, rst press [F12] to display the detail screen for the existing element, then
overtype the element name with the desired name of the new element, and press [ENTER].
• To rename an element, rst copy it to a new element as above, then delete the old element.
• To exiting a sub-application, return to the previous menu, press [PF3]. To return to the Conguration
Menu, press [Clear].
24 Chapter 1. Conguring Virtel
CHAPTER
TWO
LINES
2.1 Introduction
The “Line” is one of the basic elements of the VIRTEL conguration. A line represents a connection between
VIRTEL and another network element: an NPSI MCH, an X25 router, an X25 application (GATE, PCNE),
a CICS system, a VIRNT server, an SMTP server; alternatively, a line can represent a VIRTEL server
(HTTP, SMTP) listening on a TCP/IP port. VIRTEL call routing is performed by sets of interrelated
denitions. A call arriving on a line is processed by a set of rules which assign an entry point. The entry
point contains a set of transactions which indicate the application or external server which will process the
call. An external server refers to one or more lines on which the call may exit from VIRTEL. Each type of
entity (lines, terminals, entry points, external servers) is dened by a separate sub-application but it is often
useful to have an overall view of all the related denitions.
This chapter describes all the functions associated with the denition of lines using the Line Managment
sub-application. A detailed example will be presented later in this chapter for each type of line.
2.2 Line Management Sub-Applications
This sub-application facilitates the denition of X25 and Reverse X25 lines, APPC connections, and TCP/IP
lines. When the sub-application is started, it rst displays a summary of existing denitions in alphanumeric
order. The Line Management sub-application is invoked by pressing [PF1] in the Conguration Menu, by
pressing [PF14] in the Sub-Application Menu, or via the Multi-Session Menu using a transaction which calls
module VIR0046. This sub- application allows the management of all the line parameters under VIRTEL
control.
2.2.1 Security
When the security subsystem is active, access to Line Management sub-application from the Conguration
Menu or the Sub-Application Menu is controlled by the resource $$LINE$$. When accessed by a transaction,
normal transaction security rules will apply. Security management and securing access to sub-applications
is described in the VIRTEL Installation Guide.
2.2.2 Summary Display
The rst screen shows a summay of existing line denitions in alphanumeric order:
25
Virtel Connectivity Guide, Release 4.58
Line Summary Display
Navigation
Search Type the name (or partial name) of the required entity on the rst line under the heading “Internal
Name”, then press [Enter].
[PF2] Delete Line under cursor position.
[PF3] Return to Conguration menu.
[PF4] List terminals associated with line.
[PF6] Return to the rst page of the list.
[PF7] Display the previous page.
[PF8] Display the next page.
[PF12] Enter Line detail Screen for line under cursor position.
Modifying a line - In the summary screen position the cursor under the name of the entity to be modied.
Press [PF12]. The line detail denition screen is displayed. Type the desired modications into the appro-
priate elds then press [PF1]. Multiple denitions can be modied at the same time. Modications are not
recognized until you press the [PF1] key. Certain modications require a restart of the VIRTEL system.
Deleing a line - In the summary screen position the cursor under the name of the entity to be deleted,
then press [PF2]. The line associated with the entity to be deleted then appears highlighted, accompanied
by the message CONFIRM DELETE. Then press [PF2] again to conrm deletion. The message DELETE
OK conrms successful completion of the operation. Repeat the procedure for each entity to be deleted.
Adding a line - To add a new denition, press [PF12] at the summary screen, either with the cursor on an
existing denition to copy its attributes, or on an empty line to create a new denition from a blank screen.
26 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.2.3 Detail Display
The Line detail display is accessed from the Line summary screen via PF12(EDIT) on a selected line identied
by the cursor position. The screen shows a line detail display.
Line Detail Display
Navigation
[PF1] Update elds.
[PF3] Return to Line Summary Display.
[PF4] Display associated terminals.
[PF5] Display associated rules.
[ENTER Add new line or update elds of current line.
2.2.4 Parameters
Internal name Internal name of the line. This is the name by which VIRTEL refers to the line internally.
It must be unique within a VIRTEL instance.
External name External name of the line. This name appears in certain console messages. It can be used,
for example, to display the real name of the line or link.
Remote ident This eld contains the name or address of the remote partner. Usage depends on the line
type and protocol. The contents of this eld are described for each line type in the detailed examples
which follow.
2.2. Line Management Sub-Applications 27
Virtel Connectivity Guide, Release 4.58
Local ident This eld contains the name or address used by VIRTEL. Usage depends on the line type and
protocol. The contents of this eld are described for each line type in the detailed examples which
follow.
For an IP connection, this eld represents the listening port opened by VIRTEL. The port can be
specied in any of the following forms:
: pppp VIRTEL opens port pppp on the default home IP address of the host TCP/IP. For example,
:2048
nnn.nnn.nnn.nnn: pppp VIRTEL opens port pppp on the indicated IP address. nnn.nnn.nnn.nnn
must be a valid HOME address dened in the host TCP/IP. For example, 192.168.0.100:2048
0: pppp VIRTEL opens port pppp without associating itself with a particular IP address. VIRTEL
can receive calls on any HOME address dened in the host TCP/IP. For example, 0:2048 (or
0.0.0.0:2048)
The combination of IP address and port number must be unique. No two VIRTEL can contain a
TCP/IP line with the same IP address and port number, except that:
• multiple VIRTELs can use a single distributed VIPA address, provided that the address is
dened with a non-zero value for the TIMEDAFFINITY parameter.
• multiple XOT lines within a single VIRTEL can listen on the same IP address and port
number, providing that this same address and port number are not used by another VIRTEL.
Note: Note that the use of port numbers less than 1024 may require authorization in the prole
of the TCP/IP stack (see for example the RESTRICTLOWPORTS, PORT, and PORTRANGE
parameters of the z/OS Communications Server). In general, port numbers 1024 and above do
not require authorization.
Description Free-form description with no particular signicance or syntax requirement, except for SMTP
lines (see the detailed example of an SMTP line which follows).
Prex Terminal prex associated with the line. As a general rule, the terminal prex is a required eld. It
allows VIRTEL to associate a series of terminals to a line. Two lines cannot share the same group of
terminals. The particular details of this eld are described for each line type in the detailed examples
which follow.
Pool The name of a logical pool of terminals associated with the line. This pool is used for HTTP connec-
tions without predened terminals (see “HTTP connections with non-predened LU names”,). In all
other cases this eld can be left blank.
Entry Point Denes the default entry point used by the line. This is a required eld for HTTP and SMTP
lines. It is optional in all other cases.
Rule Set The name of the rule set used by this line. The same rule set can be used by more than one line.
If this eld is blank, no rules are used. Rules are described in detail in section .
For compatability with VIRTEL versions prior to 4.26, the rule set name is usually the same as the
internal name of the line.
Line type Denes the category to which the line belongs. VIRTEL supports the following categories of
lines:
X25 lines Represented by the values GATE or FASTC
Support for this type of line is governed by the presence of the parameters MINITEL=YES,
GATE=GENERAL and possibly FASTC=YES in the VIRTCT.
28 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Reverse-X25 lines Represented by the values /GATE, /FASTC, or /PCNE
Support for this type of line does not require any special parameters in the VIRTCT.
APPC lines Represented by the values APPC1 or APPC2.
APPC1 represents a link with a BATCH environment
APPC2 represents all other types of APPC link with partners such as CICS or NT. Support for
this type of line does not require any special parameters in the VIRTCT.
TCP/IP lines Represented by the values TCP1 or TCP2.
Support for this type of line is governed by the presence of the parameter TCP1 or TCP2 in
the VIRTCT. Used for HTTP, SMTP, ICONNECT, XOT, NATIVE, VIRPESIT, VIRNEOX, or
VIRPASS TCP lines.
Cross-memory lines Represented by the values XM1 or XM2
Support for this type of line is governed by the presence of the parameter XM1 or XM2 in the
VIRTCT. Used for VIRPASS XM lines.
MQSeries lines Represented by the values MQ1 or MQ2
Support for this type of line is governed by the presence of the parameter MQ1 or MQ2 in the
VIRTCT.
Batch lines Represented by the values BATCH1 or BATCH2
Support for this type of line is governed by the presence of the parameter BATCH1 or BATCH2
in the VIRTCT.
Possible calls Determines which calls can be made on this line. Since the line management interface is
common to all types of lines, all values between 0 and 3 are accepted.
In addition to being used to authorize incoming, outgoing, or both incoming and outgoing calls, this
parameter also has an eect during VIRTEL startup. Any line which has “Possible calls” set to 0
will not be activated at VIRTEL startup. Also note the“Possible calls” eld in the denition of the
associated terminals.
Startup prerequisite Allows conditional startup of the line. If this eld is blank, VIRTEL starts the line
automatically at system startup.
WAIT-LINE(n-xxxxxx) Waits for line n-xxxxxx to start. The name specied can be either the
internal or external name of the other line.
WAIT-MINUTES(nn) Waits nn minutes after system startup before starting this line.
WAIT-COMMAND Waits for a console command LINE=linename,START (see “List of com-
mands” in the VIRTEL Audit And Performance Guide)
WAIT-PARTNER Waits until VIRTEL receives an SNA BIND command from its partner LU.
MIMIC-LINE(n-xxxxxx) species that this line starts and stops in synchronisation with line n-
xxxxxx. The name specied can be either the internal or external name of the other line.
Protocol program Indicates the protocol used for a TCP, XM, or MQ type line. The following values are
valid for a TCP line:
HTTP or VIRHTTP For an HTTP line
NATIVE2(P) or NATIVE4(P) For a line in native TCP/IP mode
SMTP or VIRSMTP For an SMTP line
ICONNECT For a RESUME TPIPE connection with IMS Connect
2.2. Line Management Sub-Applications 29
Virtel Connectivity Guide, Release 4.58
VIRPASS For a VIRPASS TCP connection with an VIRNT or VIRKIX system
VIRPESIT For a TCP connection with a le transfer program such as CFT/IP
VIRNEOX For a TCP connection with a remote program using the VIRNEOX protocol
XOT or VIRXOT For an XOT line
The following values are valid for an XM line:
VIRPASS For a VIRPASS XM connection with a VIRKIX system running on the same MVS
The following values are valid for an MQ line:
RAW For communication via an MQSeries message queue
PREFIXED or PREFIX12 For communication via an MQSeries message queue. This is similar to
the RAW protocol except that VIRTEL adds 12 bytes of additional context information for the
application program.
PREFIX20 For communication via an MQSeries message queue. This is similar to the RAW protocol
except that VIRTEL adds 20 bytes of additional context information for the application program.
Note: This eld must not be completed for lines whose type is APPC1, APPC2, GATE, FASTC,
/GATE, /FASTC, or /PCNE.
Security program Reserved for future use.
Time out Inactivity time in seconds after which the action specied in the following eld will be taken.
The value 0 inhibits the time out.
Action if T/O Action taken if a time out occurs. 0 = no action
1 = keepalive
KEEPALIVE is a message sent by the TCP/IP stack, during periods of inactivity, to check whether the
connection has been broken. The value 1 is thus only valid for lines of type TCP. After a certain number
of KEEPALIVE messages have been sent without being acknowledged by the partner (the number is
determined by the TCP/IP stack), the session will be considered unusable and the connection will be
terminated.
OS/390 and z/OS KEEPALIVE must also be activated in the PROFILE of the TCP/IP stack (refer to
parameters KEEPALIVEOPTIONS or TCPCONFIG INTERVAL). For z/OS V1R7 and later, the time
out value specied in the preceding eld determines the interval between KEEPALIVE messages. If the
time out value is zero then the default TCPCONFIG INTERVAL will be used. For OS/390 and z/OS
prior to V1R7, the TCP/IP stack uses a single KEEPALIVE interval which applies to all sessions, and
the time out value specied in the preceding eld is ignored.
TCP/IP for VSE KEEPALIVE is managed globally by the TCP/IP command SET PULSE_TIME, and
the parameters “Time Out” and “Action=1” are ignored.
Window Window size at the packet level. This parameter is meaningful only for X25 (GATE or FASTC)
and XOT lines.
Must correspond with your X25 service provider subscription, or with the X25 switch parameters if
this type of equipment is used.
Packet Packet size. Usually 128. This parameter is meaningful only for X25 (GATE or FASTC) and XOT
lines.
Must correspond with your TRANSPAC subscription, or with the X25 switch parameters if this type
of equipment is used.
30 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Replaces the PACKET global parameter in the VIRTCT for versions prior to 4.0.
Pad This parameter is meaningful only for X25 GATE non Fast-Connect lines and AntiGATE lines.
INTEG Data without X’00’ prex
TRANSP Data with prex
NO Data with prex
Must correspond with the NPSI parameters, or with the X25 switch parameters if this type of equipment
is used.
Tran This parameter is meaningful only for Reverse-X25 AntiPCNE lines. Species whether
EBCDIC/ASCII translation occurs.
EVEN ASCII data from the network is translated to EBCDIC when presented to the application,
and vice versa (Even Parity)
ODD Ditto (Odd Parity)
NO No ASCII/EBCDIC translation
Retries Number of attempts to reacquire auto-activated terminals during VIRTEL startup. The delay
between attempts is specied by the “Delay” parameter.
Delay Interval in seconds between attempts to reacquire terminals. The default delay is 2 seconds.
2.2. Line Management Sub-Applications 31
Virtel Connectivity Guide, Release 4.58
2.3 Line Overview Sub-Application
The Lines Overiew display presents an overall view and allows the administrator to zoom in on individual
denitions to display and optionally modify the detailed denition. Missing denitions (those referenced by
another entity but not dened in the conguration) are highlighted in red. This sub-application allows the
administrator to display and optionally modify the various entities associated with each line dened in the
VIRTEL conguration. The Lines Overview sub-application is invoked by pressing [PF8] at the Conguration
Menu, by pressing [PF15] at the Sub-Application Menu, or via the Multi-Session using a transaction which
calls module VIR0049.
Lines overview summary display
32 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.4 HTTP Inbound line
When an HTTP line is started, VIRTEL becomes an HTTP server, authorising connections from a web
browser to applications at the host site. Activation of this type of line is subject to the presence of the TCP1
parameter in the VIRTCT, as well as to a denition providing linkage to a le containing the HTML pages.
Denition of an HTTP line
Remote ident Always blank.
Local ident This is the VIRTEL IP address and port number which browser users must specify in order to
connect to VIRTEL. If the port number is omitted then the default is port 80. See the description of
the “Local ident” eld under the heading “Line Parameters”, for more details about how to code this
eld.
Prex Terminal name prex (see below).
Entry Point When dening an HTTP line, it is obligatory to dene a default entry point. This entry point
will be used for all incoming calls which do not match any of the rules of the line. The entry point
contains a list of transactions, and these transactions determine which directories are used to retrieve
the HTML pages, and which 3270 applications are accessible to the user.
Note: According to the type of application accessed, each transaction must refer to one of the
terminal sub-groups associated with the HTTP line (see ”HTTP terminals” below).
For type 1 (Application) transactions The prex will be that of the terminal sub-group with an
associated relay.
For type 2 (Virtel) or type 4 (Page) transactions The prex will be that of the terminal sub-
group without an associated relay.
For type 3 (Server) transactions No terminal prex is required.
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
2.4. HTTP Inbound line 33
Virtel Connectivity Guide, Release 4.58
Possible calls Specify 1 (incoming calls only) to indicate that this line represents a listening port where
VIRTEL is acting as an HTTP server.
For the case where VIRTEL acts as an HTTP requester, refer to the following section “Denition of a
HTTP Outbound line”.
Protocol VIRHTTP or HTTP.
Window Always 0.
Packet Always 0.
Pad Always blank.
Tran Always blank.
2.4.1 Terminal Denitions
An HTTP line uses two sub-groups of type-3 terminals having a common prex (in this case CL). Each
terminal in the rst sub-group represents one session between the client browser and VIRTEL; no relay
is congured for this sub-group. Each terminal in the second sub-group represents one session between
VIRTEL and a host application; in this sub-group, either a relay must be congured for each terminal, or
the sub-group must refer to “logical pool of relays”. Whichever method is chosen, each relay must be dened
by an APPL statement in a VTAM node of type APPL. Either explicit or repeated terminal denitions may
be used.
Press [PF4] at the HTTP line detail denition screen to display the list of associated terminals whose prex
matches the prex specied in the line denition. If the terminals refer to a logical pool, the pool itself
may have a dierent prex and will therefore not be displayed. In this case you can press [PF2] at the
Conguration Menu to display a list of all terminals.
The example below shows the terminals for two HTTP lines which share a logical pool of relays. This
list was displayed by pressing [PF2] at the Conguration Menu. The terminals with prex CL belong to
line C-HTTP, while the terminals with prex DE belong to line W-HTTP. For line C-HTTP, the rst sub-
group consists of terminals CLLOC000-049 without a relay. The second sub-group consists of terminals
CLVTA000-079 which refer to a logical pool of relays named
*W2HPOOL. For line W-HTTP, the rst sub-group is DELOC000-009, and the second sub-group is DE-
VTA000-015 which also refers to the logical pool named *W2HPOOL. The logical pool itself consists of
terminals W2HTP000-015 whose relay LU names are REHVT000-079. The logical pool also refers to a pool
of associated printer LU’s. The printers are dened with terminal names W2HIP000-079 and LU names
REHIP000-079. In each case, the terminal name is an internal name used only within VIRTEL, while the
relay name is an LU name dened by a VTAM APPL statement. The relay LU name is the name by which
the terminal is known to CICS or other VTAM applications.
34 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Terminals associated with an HTTP line
HTTP terminals without relay
2.4. HTTP Inbound line 35
Virtel Connectivity Guide, Release 4.58
HTTP terminals with relay
logical pool of relays for HTTP
36 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Associated printer relays for HTTP
Refer to the VIRTEL Web Access Guide for further information about printers.
2.4.2 VTAM Terminal Denitions
HTTP relay LU’s must be dened to VTAM by means of APPL statements in an application major node,
as shown in the following example:
C52VIRTM VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
*RHTVTxxx : Relay for VTAM appl accessed by WEB to HOST *
* ------------------------------------------------------------------ *
RHTVT000 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
RHTVT001 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
RHTVT002 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
RHTVT003 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
* ------------------------------------------------------------------ *
*RHTIPxxx : Printer relays for WEB to HOST terminals *
* ------------------------------------------------------------------ *
RHTIP000 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=DSILGMOD,EAS=1
RHTIP001 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=DSILGMOD,EAS=1
RHTIP003 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=DSILGMOD,EAS=1
RHTIP004 APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=DSILGMOD,EAS=1
VTAM denitions for HTTP terminals
2.4.3 CICS Denitions
The HTTP relay LU’s must also be dened to CICS, as shown in the following example:
2.4. HTTP Inbound line 37
Virtel Connectivity Guide, Release 4.58
*VIRTEL 3270 TERMINALS FOR WEB2HOST
DEFINE TERMINAL(T000) GROUP(VIRTEL) TYPETERM(DFHLU2E2)
NETNAME(RHTVT000) PRINTER(I000)
DESC(VIRTEL WEB TO HOST TERMINAL)
DEFINE TERMINAL(T001) GROUP(VIRTEL) TYPETERM(DFHLU2E2)
NETNAME(RHTVT001) PRINTER(I001)
DESC(VIRTEL WEB TO HOST TERMINAL)
DEFINE TERMINAL(T002) GROUP(VIRTEL) TYPETERM(DFHLU2E2)
NETNAME(RHTVT002) PRINTER(I002)
DESC(VIRTEL WEB TO HOST TERMINAL)
DEFINE TERMINAL(T003) GROUP(VIRTEL) TYPETERM(DFHLU2E2)
NETNAME(RHTVT003) PRINTER(I003)
DESC(VIRTEL WEB TO HOST TERMINAL)
*VIRTEL 3284 PRINTERS FOR WEB2HOST
DEFINE TERMINAL(I000) GROUP(VIRTEL) TYPETERM(DFHLU3)
NETNAME(RHTIP000)
DESC(VIRTEL WEB TO HOST PRINTER)
DEFINE TERMINAL(I001) GROUP(VIRTEL) TYPETERM(DFHLU3)
NETNAME(RHTIP001)
DESC(VIRTEL WEB TO HOST PRINTER)
DEFINE TERMINAL(I002) GROUP(VIRTEL) TYPETERM(DFHLU3)
NETNAME(RHTIP002)
DESC(VIRTEL WEB TO HOST PRINTER)
DEFINE TERMINAL(I003) GROUP(VIRTEL) TYPETERM(DFHLU3)
NETNAME(RHTIP003)
DESC(VIRTEL WEB TO HOST PRINTER)
This job is supplied in member CSDW2H of the VIRTEL SAMPLIB.
2.5 HTTP Outbound line
An HTTP Outbound line allows VIRTEL to act as an HTTP requester. Activation of this type of line is
subject to the presence of the TCP1 parameter in the VIRTCT.
By means of the OPTION$ FOR-HTTP and SEND$ TO-LINE instructions, a VIRTEL scenario can make
requests to the remote HTTP server whose address is specied in the HTTP Outbound line denition.
Multiple HTTP Outbound lines may be dened to allow requests to be sent to dierent HTTP servers.
Refer to “VIRTEL Web Modernisation Scenarios” in the VIRTEL Web Access Guide for examples of the
OPTION$ FOR-HTTP instruction. The $SITE$ denes the IP address of the outbound server. It is passed
via a sceanrio. See the OPTION$ FOR-HTTP scenario instruction.
38 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Denition of an HTTP Outbound line
2.5.1 Parameters
Internal name Must be unique.
External name Should be unique. Either the internal name or the external name may be specied in the
SEND$ TO-LINE instruction in the scenario.
Remote ident This is the IP address and port number of the remote HTTP server. The format is
nnn.nnn.nnn.nnn:pppp where nnn.nnn.nnn.nnn is the IP address and pppp is the port number.
The port number (normallyport 80) must be specied, there is no default.
The remote HTTP server may also be specied by its DNS name and port number, for example
webservices.mycompany.com:80
The special value $SITE$ indicates that the name and port number of the remote HTTP server are
specied in the SITE parameter of the OPTION$ FOR-HTTP instruction.
Local ident $NONE$ indicates that VIRTEL will not open a listening port for this line.
Prex Leave blank. No terminals are required for an HTTP Outbound line.
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls Specify 2 to indicate that this line is used for outbound calls.
Protocol VIRHTTP or HTTP.
2.6 HTTP Outbound SMTP line
An SMTP line establishes a TCP/IP link between VIRTEL and an external SMTP server. The external
SMTP server receives outgoing mail from VIRTEL for distribution to users. The SMTP line also denes
2.6. HTTP Outbound SMTP line 39
Virtel Connectivity Guide, Release 4.58
the characteristics of VIRTEL’s internal SMTP server which receives incoming mail sent to VIRTEL. The
activation of this type of line requires the presence of the TCP1 parameter in the VIRTCT.
..note:: In case of SMTP problems, use the command F VIRTEL,TRACE,L=S-SMTP to trace the dialog
between VIRTEL and the SMTP server. The trace output is written to SYSPRINT or SYSLST.
SMTP line denition
2.6.1 Parameters
Remote ident This eld is required and represents the IP address and port number of the SMTP server
to which VIRTEL sends outgoing mail.
Local ident The IP address and port number on which VIRTEL listens for incoming mail. For details of
how to code this eld, refer to “Local ident” under the heading “Line Parameters”,.
Description The sender name generated in outgoing e-mails. Not used for incoming e-mails.
Generally, the description eld does not contain any signicant information. However, in the case of
an SMTP line, the contents of this eld are used by VIRTEL.
The description eld for an SMTP line must be in a specic format. It must contain a domain name,
followed by an e-mail address enclosed in angle brackets (characters “<” and “>”). Everything up
to the rst angle bracket is the operand of the HELO command which VIRTEL sends to the SMTP
server. The e-mail address in angle brackets is the default operand of the MAIL FROM command
which VIRTEL sends to the SMTP server. This default e-mail address can optionally be overridden by
the sending application by means of the FAD4 structured eld. The e-mail address used will normally
need to be dened to the SMTP server.
Prex Terminal name prex (see below).
40 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Entry Point When dening an SMTP line, it is obligatory to dene a default entry point. This entry point
will be used for all incoming calls which do not match any of the rules of the line.
Entry points for use with SMTP lines are described under the heading “Incoming E-mails” in the
VIRTEL Web Access Guide.
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls Direction of calls.
The value 3 must be used in order to allow exchanges in both directions between VIRTEL and the
partner SMTP server.
Protocol Always SMTP.
Window Always 0.
Packet Always 0.
Pad Always blank.
Tran Always blank.
SMTP terminals
By pressing [PF4], the list of terminals associated with the SMTP line will be displayed. An
SMTP line uses a single sub- group of type-3 terminals having a common prex (in this case
SM). The number of terminals dened determines the number of simultaneous SMTP sessions
authorised. Either explicit or repeated Terminal Denitions may be used.
The example below shows a group of 16 SMTP terminals with associated relays:
SMTP Terminal Denitions
2.6.2 Terminal Denitions
Terminal The terminal name must match the prex of the line.
2.6. HTTP Outbound SMTP line 41
Virtel Connectivity Guide, Release 4.58
Relay A relay LU must be specied if incoming e-mails are used to trigger the start of a CICS transaction
(or another VTAM application). The relay LU’s must be dened by APPL statements in a VTAM
application major node, as described below.
Entry point Leave blank. The entry point is dened in the line (or in the rules of the line) for this type of
terminal.
Type de terminal Always 3.
Compression Always 2.
Possible Calls Always 3.
Repeat The number of terminals dened.
2.6.3 VTAM Terminal Denitions
RWSVT200 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RWSVT201 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RWSVT202 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RWSVT203 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
VTAM denitions for SMTP relay LUs
2.6.4 CICS Denitions
Where incoming e-mails are used to trigger a CICS transaction (or other VTAM application), the SMTP
relay LU’s must be dened by APPL statements in a VTAM application major node, as shown in this
example:
DEFINE TYPETERM(SMTP3270) GROUP(VIRTSMTP)
DESCRIPTION(TYPETERM FOR SMTP PSEUDO-TERMINAL)
DEVICE(3270) TERMMODEL(2) SHIPPABLE(YES) RECEIVESIZE(16384)
PAGESIZE(24,80) DEFSCREEN(24,80) EXTENDEDDS(YES) QUERY(ALL)
TTI(YES) RELREQ(YES) DISCREQ(YES) LOGONMSG(NO) UCTRAN(NO)
DEFINE TERMINAL(SM00) GROUP(VIRTSMTP)
DESCRIPTION(PSEUDO-TERMINAL FOR SMTP)
TYPETERM(SMTP3270) NETNAME(RWSVT200) USERID(SPVIRSTC)
DEFINE TERMINAL(SM01) GROUP(VIRTSMTP)
DESCRIPTION(PSEUDO-TERMINAL FOR SMTP)
TYPETERM(SMTP3270) NETNAME(RWSVT201) USERID(SPVIRSTC)
DEFINE TERMINAL(SM02) GROUP(VIRTSMTP)
DESCRIPTION(PSEUDO-TERMINAL FOR SMTP)
TYPETERM(SMTP3270) NETNAME(RWSVT202) USERID(SPVIRSTC)
DEFINE TERMINAL(SM03) GROUP(VIRTSMTP)
DESCRIPTION(PSEUDO-TERMINAL FOR SMTP)
TYPETERM(SMTP3270) NETNAME(RWSVT203) USERID(SPVIRSTC)
42 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.7 IMS Connect line
An IMS Connect line establishes a TCP/IP connection between VIRTEL and IMS Connect using the RE-
SUME TPIPE protocol. Once the connection is established, IMS application programs running in an MPP
or BMP region can send requests to VIRTEL using the ICAL DL/I call. VIRTEL processes these requests
by launching a customer-written scenario. The scenario can perform actions such as making an outbound
HTTP call to a web service before returning the result to the IMS application program. Activation of this
type of line requires the presence of the TCP1 parameter in the VIRTCT.
Denition of an IMS Connect line
2.7.1 Parameters
Internal name The VIRTEL internal name for this connection.
External name Must match the IMS destination id (IRM_IMSDestId).
Remote ident IP address of IMS Connect followed by the port number.
Local ident Leave blank.
Prex Terminal name prex (see below).
Entry Point The entry point name must match the IMS TPIPE name (IRM_CLIENTID).
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls Always 1.
Protocol Always ICONNECT.
2.7. IMS Connect line 43
Virtel Connectivity Guide, Release 4.58
2.7.2 Terminals Denitions
Press [PF4] at the Line Detail Denition screen to display the list of terminals associated with an IMS
Connect line. An IMS Connect line uses a single sub-group of type-3 terminals having a common prex
(ICAL in this example). No relays are dened for this type of line. The number of terminals dened
determines the maximum number of simultaneous RESUME TPIPE sessions between VIRTEL and IMS
Connect.
Denition of terminals associated with an IMS Connect line
Terminal The terminal name must match the prex of the line.
Relais Leave blank.
Entry point Leave blank.
Terminal Type Always 3.
Compression Always 2.
Possible calls Always 1.
Repeat Number of terminals (RESUME TPIPE sessions) dened.
2.7.3 Entry Point
Each IMS Connect line must have an associated Entry Point whose name is specied in the line denition.
An example is shown below:
44 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Denition of entry point associated with an IMS Connect line
Name The name of the entry point must match the IMS TPIPE name specied in the IRM_CLIENTID
parameter of the IMS Connect denition.
Transactions Prex of associated transaction names (see next section).
Emulation Always SCENARIO.
Directory for scenarios The name of the VIRTEL directory which contains the scenario(s) for processing
requests from IMS.
2.7.4 Transactions
Each IMS Connect entry point must have one or more associated transactions. Press [PF4] at the Entry
Point Detail Denition screen to display the list of transactions associated with an IMS Connect entry point.
The transaction denition species the name of the scenario which will be invoked to process an incoming
request from IMS. If the incoming request does not specify a transaction name, or if the specied transaction
name is not dened in the entry point, then VIRTEL will invoke the transaction whose external name is
the same as the entry point name. If there is no such default transaction, then the request is rejected and
VIRTEL issues message VIRIC57E.
2.7. IMS Connect line 45
Virtel Connectivity Guide, Release 4.58
Denition of a transaction associated with an IMS Connect entry point
Internal name Must match the transaction prex specied in the entry point.
External name This is the transaction name specied by the IMS application in the message header. For
the default transaction, the external name must be the same as the entry point name.
Application Always $NONE$.
Application type Always 2.
Security Always 0.
TIOA at logon Always &/S.
Initial scenario The name of the VIRTEL scenario which will process requests from IMS for this transac-
tion.
2.7.5 Scenarios
When a scenario is invoked to process a request message from IMS connect, VIRTEL places the
contents of the request message in the variable $INFILE$. After processing the message, the
scenario returns a response message to IMS by means of the SEND$ AS-ANSWER instruction.
By way of illustration, the simple example shown below converts the request message to uppercase
before sending it back as a response message to IMS:
OTMACL SCREENS APPL=OTMACL
*
* Scenario for testing an IMS CONNECT connection
*
SCENARIO INITIAL
*
CONVERT$ EBCDIC-TO-UPPERCASE,VAR='$INFILE$'
SEND$ AS-ANSWER,VAR='$INFILE$',TYPE='TEXT'
*
46 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
SCENARIO END
*
SCRNEND
END
Example scenario for processing an IMS Connect request
..note:
More complex scenarios may be constructed with the aid of VIRTEL Studio.
2.7.6 Message format
Messages sent from an IMS application to VIRTEL may be prexed by a 12-byte header. The
format of the header is shown in the gure below:
Bytes Length EBCDIC Meaning
0 - 3 4 /V1/ Identies type of prex
4 - 11 8 xxxxxx Externql transaction name. Left justied and padded with blanks
Format of an IMS Connect message header
All data following the header is treated as binary data which is passed to the scenario without translation
in the $INFILE$ variable.
2.7. IMS Connect line 47
Virtel Connectivity Guide, Release 4.58
2.8 MQ line
An MQ line establishes a connection between VIRTEL and an MQSeries message queue. Each MQ line can
receive messages from, or send messages to, one MQSeries message queue. Activation of this type of line
requires the presence of the MQ1 or MQ2 parameter in the VIRTCT. The queue can be shared with another
application (another VIRTEL for instance) or used in exclusive mode depending on its own denition.
2.8.1 Parameters
Remote ident For the RAW protocol: Leave blank.
For the PREFIXED, PREFIX12, and PREFIX20 protocols: The special value $REPLYTOQ indicates
that outbound messages are sent to the destination indicated by the REPLYTOQ and REPLYTO-
QMGR parameters taken from the inbound message and saved in the 12- or 20-byte header.
Local ident The name of the MQSeries message queue. The queue name prex specied in the MQn
parameter of the VIRTCT will be added to the front of this name. Refer to “Parameters of the
VIRTCT” in the VIRTEL Installation Guide for details of the MQn parameter.
Prex Terminal name prex (see below).
Entry Point Required for MQ input queue.
Line type One of the MQn protocols dened in the VIRTCT, for example MQ1.
Possible calls Specify one of the following values:
-1 = Input: VIRTEL receives messages from the MQSeries queue -2 = Output: VIRTEL writes
messages to the MQSeries queue
48 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Protocol RAW, PREFIXED, PREFIX12, or PREFIX20.
Tran
Specify the way in which messages are processed on the line.
-STR = The messages are processed as MQFMT_STRING formatted messages. This will allow MQ
to perform the appropriate character set translations between the communicating systems. To support
this feature, the PTF5135 must be applied on the system.
-no value = The messages are processed as MQFMT_NONE formatted messages.
Navigation
Press [PF4] at the line denition screen to display the list of terminals associated with an MQ line. An MQ
line uses a single sub-group of type-3 terminals having a common prex (MQIN in this example). The number
of terminals dened determines the maximum number of messages which can be processed simultaneously
by VIRTEL.
2.8.2 Terminal Parameters
Terminal The terminal name must match the prex of the line.
Relais Leave blank.
Entry point Leave blank.
Terminal Type Always 3.
2.8. MQ line 49
Virtel Connectivity Guide, Release 4.58
Compression Always 2.
Possible calls Always 3.
Repeat Number of terminals dened.
50 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.9 Batch line
A batch line allows VIRTEL to process HTTP requests in batch mode. When a batch line is dened in the
VIRTEL conguration, VIRTEL reads HTTP requests from an input sequential le at startup, processes
the requests, writes the responses to an output sequential le, and shuts down. Activation of this type of
line is subject to the presence of the BATCHn parameter in the VIRTCT.
2.9.1 Parameters
Remote ident Always blank.
Local ident Always blank.
Prex Terminal name prex (see below).
Entry Point When dening a batch line, it is obligatory to dene a default entry point. This entry point
is similar to the entry point used for an HTTP line. The entry point contains a list of transactions,
and these transactions determine which directories are used to retrieve page templates, and which 3270
applications are accessible to the batch requests.
Each transaction must refer to one of the terminal sub-groups associated with the batch line (see
”Batch terminals” below).
For type 1 (Application) transactions: The prex will be that of the terminal sub-group with an
associated relay.
For type 2 (Virtel) or type 4 (Page) transactions The prex will be that of the terminal sub-
group without an associated relay.
For type 3 (Server) transactions No terminal prex is required.
Line type BATCH1 or BATCH2, corresponding to one of the BATCH parameters dened in the VIRTCT.
Possible calls Specify 1 (incoming calls only).
2.9. Batch line 51
Virtel Connectivity Guide, Release 4.58
Protocol VIRHTTP or HTTP.
Window Always 0.
Packet Always 0.
Pad Always blank.
Tran Always blank.
2.9.2 Terminal Denitions
Like an HTTP line, a batch line uses up to two sub-groups of type-3 terminals having a common
prex (in this case BT1). Refer to “HTTP terminals” 26 for further details. If the batch requests
do not require connection to a host VTAM application, then it is only necessary to dene the
rst terminal sub-group (the sub-group without relays).
Press [PF4] at the line detail denition screen to display the list of associated terminals whose
prex matches the prex specied in the line denition. Then press [PF12] to display the terminal
detail denition. The example below shows the terminals for a batch line without relays:
Denition of terminals without relay for a batch line
52 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.10 Native TCP/IP Gateway line
VIRTEL can act as an IP-to-SNA gateway allowing existing VTAM applications to communicate
with partner applications via the IP network. By connecting to a VIRTEL NATIVE TCP/IP
port, a remote application can establish a TCP/IP session with VIRTEL and exchange messages
with a host VTAM application using a simple record-oriented protocol.
The connection is always established by the remote TCP/IP application, but messages can ow
in both directions. Each message exchanged between VIRTEL and the partner application is
preceded by a two- or four-byte length eld.
Typically the host application is a CICS application designed to communicate with banking
terminals such as the IBM 3650.
The activation of this type of line requires the presence of the >TCP1 parameter in the VIRTCT.
2.10.1 Parameters
Remote ident Not used for a NATIVE TCP/IP line.
Local ident The IP address and port number on which VIRTEL listens for incoming connections from the
partner application. For details of how to code this eld, refer to “Local ident” under the heading
“Line Parameters”.
Prex Terminal name prex (see below).
Entry Point The default entry point will be used for all incoming calls which do not match any of the rules
of the line. Entry points for use with native TCP/IP lines must specify Emulation type $NONE$
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls Specify 1 to allow inbound calls.
2.10. Native TCP/IP Gateway line 53
Virtel Connectivity Guide, Release 4.58
Protocol NATIVE2 or NATIVE2P for native TCP/IP protocol with a two-byte length eld NATIVE4 or
NATIVE4P for native TCP/IP protocol with a four-byte length eld
Packet Specify a packet size sucient to contain the largest message sent by either the host or the partner
application, plus 2 or 4 bytes for the length eld.
2.10.2 Line Terminals
By pressing [PF4], the list of terminals associated with the NATIVE TCP/IP line will be dis-
played. A NATIVE TCP/IP line uses a single group of type-3 terminals having a common prex
(VIP in this example). The number of terminals dened determines the number of simultaneous
conversations authorised.
The example below shows a group of 4 NATIVE TCP/IP terminals:
2.10.3 Terminal Parameters
Terminal The terminal name must match the prex of the line.
Relay Specify the name of the relay pool which denes the terminal LU names as seen by the VTAM
application. The rst character is an asterisk indicating that this is the name of a pool.
Entry point Leave blank. The entry point is dened in the line (or in the rules of the line) for this type of
terminal.
Terminal type Always 3.
Compression Always 2.
Possible Calls Always 3.
Repeat The number of terminals dened.
54 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.10.4 Relay Pool
The gure below shows the denition of the NATIVE TCP/IP relay pool:
2.10.5 VTAM terminals denitions
Relay LU’s must be dened to VTAM by means of APPL statements in an application major node, as shown
in the following example:
VIRTAPPL VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
*RVIPLU00 : VTAM relays for VIRTEL NATIVE TCP/IP terminals *
* ------------------------------------------------------------------ *
RVIPLU00 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RVIPLU01 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RVIPLU02 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RVIPLU03 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
VTAM denitions for NATIVE TCP/IP relay LU’s
2.10.6 CICS Denitions
The NATIVE TCP/IP relay LU’s must also be dened to CICS, as shown in the following example:
DEFINE TYPETERM(DT3650) GROUP(VIRTEL)
DESC(3650 FOR VIRTEL TCP/IP)
DEVICE(3650) SESSIONTYPE(USERPROG)
SENDSIZE(1536) RECEIVESIZE(1536)
DEFINE TERMINAL(VR00) GROUP(VIRTEL) NETNAME(RVIPLU00)
DESC(VIRTEL NATIVE TCP/IP TERMINAL) TYPETERM(DT3650)
DEFINE TERMINAL(VR01) GROUP(VIRTEL) NETNAME(RVIPLU01)
2.10. Native TCP/IP Gateway line 55
Virtel Connectivity Guide, Release 4.58
DESC(VIRTEL NATIVE TCP/IP TERMINAL) TYPETERM(DT3650)
DEFINE TERMINAL(VR02) GROUP(VIRTEL) NETNAME(RVIPLU02)
DESC(VIRTEL NATIVE TCP/IP TERMINAL) TYPETERM(DT3650)
DEFINE TERMINAL(VR03) GROUP(VIRTEL) NETNAME(RVIPLU03)
DESC(VIRTEL NATIVE TCP/IP TERMINAL) TYPETERM(DT3650)
2.10.7 Message format
All messages sent on a NATIVE TCP/IP conversation are prexed by a 2-byte or 4-byte header. The format
of the header for the NATIVE2 protocol is shown in the gure below:
Bytes Length Meaning
0 -
1
2 Message length in bytes, excluding the length eld itself This is a 16-bit unsigned binary
number in big-endian format (Most signicant byte rst)
Format of NATIVE2 message header
The format of the header for the NATIVE4 protocol is shown in the gure below:
Bytes Length Meaning
0 -
3
4 Message length in bytes, excluding the length eld itself This is a 32-bit unsigned binary
number in big-endian format (Most signicant byte rst)
Format of NATIVE4 message header
All data following the header is treated as binary data which is passed to the CICS application without
translation. The maximum message length is specied in the denition of the NATIVE TCP/IP line.
The variants NATIVE2P and NATIVE4P may be used if the terminal is dened to the application as a
3270 (LU2) device. In this case, VIRTEL will add the prex X‘7D4040’ to inbound messages before sending
them to the application, and will remove the 3270 prex (for example X’F1C1’) from outbound messages
before sending them to the terminal. The message format to the terminal is the same as described above for
NATIVE2 and NATIVE4.
56 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.11 VIRPASS TCP line (VIRKIX)
Communication between VIRTEL and CICS can be established via APPC, TCP/IP, or Cross-memory. This
section describes communications in TCP/IP mode using the VIRKIX program on the CICS side.
2.11.1 Parameters
Remote ident Contains the IP address and port number of the CICS side of the link. It must match
the elds “adresse TCP/IP” and “port serveur” of the TCP/IP interface dened in VIRKIX. This
eld should only be used when the VIRKIX relay type is “Virpass TCP/IP” (previously known as
“Virpass Symétrique”). If the VIRKIX relay type is “Virpass Asymétrique” (previously known as
“Virtel TCP/IP”), this eld must be blank, and VIRTEL will wait for VIRKIX to make the connection
on he address specied in the “Local ident” eld.
Local ident Must be specied. Contains the IP address and port number of the VIRTEL side of the link.
Must match the elds “Adresse TCP/IP” and “port du serveur” specied in the VIRPASS interface
(relay type “Virpass TCP/IP” or “Virpass Asymétrique”) dened in VIRKIX.
Prex Terminal name prex (see below).
Entry point Leave blank.
Line type TCP1
Possible calls Always 3.
Protocol Always VIRPASS.
Window Always 0.
Packet Always 0.
Pad, Tran Always blank.
2.11. VIRPASS TCP line (VIRKIX) 57
Virtel Connectivity Guide, Release 4.58
2.11.2 Terminal Denitions
A VIRPASS TCP line for communication with VIRKIX uses a single sub-group of terminals
dedicated to outgoing calls. Either explicit or repeated denitions can be used. The terminals
are dened as type 3, compression 2, and the “Possible calls” eld must be set to 2. The
“Relay” eld in the terminal denition must contain the name of the VIRKIX relay which will
be activated at connection time. In the case of incoming X25 calls this relay is dened in the
VIRKIX menu “Interface X25” – “Appels X25 entrant”. The “Type of line” eld in the relay
denition must contain the value X25VIRPA (or E25TCPIP in previous versions of VIRKIX).
Unlike other terminal types, the relay name specied here is not the name of a VTAM LU.
Terminals on a VIRPASS TCP line for VIRKIX
58 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.12 VIRPASS TCP line (VIRNT)
A VIRNT system can be connected to VIRTEL to act as an X25 gateway handling incoming and outgoing
connections to and from VIRTEL, or to act as a LECAM server. Communication between VIRTEL and
VIRNT can be established using either an APPC line or a TCP/IP line. This section describes TCP/IP
mode.
2.12.1 Parameters
Remote ident Always blank.
Local ident This eld must be the same as the TCP/IP port referenced under the heading “HOST IP
Port” in the VIRPASS.INI le on the VIRNT system.
Prex Terminal name prex (see below).
Entry Point Not required for this type of line.
Line type TCP1
Possible calls No special restriction.
Protocol Always VIRPASS.
Window Always 0.
Packet Always 0.
Pad, Tran Always blank.
A VIRPASS TCP connection with a VIRNT system can use up to two sub-groups of terminals. The rst
sub-group is dedicated to incoming calls and has an associated relay. The second sub-group is dedicated to
outgoing calls and has no associated relay. The two sub-groups have a common prex which associates them
with the line. Either explicit or repeated terminal denitions may be used.
2.12. VIRPASS TCP line (VIRNT) 59
Virtel Connectivity Guide, Release 4.58
NTTCE980 0020 RNTTC000 $X25$ 3 1
NTTCS980 0020 $X25$ 3 2
2.12.2 Terminal Denitions
Each terminal in the pool dedicated to incoming calls must have an associated relay. The terminals are
dened as type 3, compression 2, and the “Possible Calls” eld must be set to 1:
Inbound terminals for a VIRPASS TCP line for VIRNT
Terminals in the pool dedicated to outgoing calls do not have an associated relay. The terminals
are dened as type 3, compression 2, and the “Possible Calls” eld must be set to 2:
60 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Outbound terminals for a VIRPASS TCP line for VIRNT
2.12. VIRPASS TCP line (VIRNT) 61
Virtel Connectivity Guide, Release 4.58
2.13 VIRPASS XM line (VIRKIX)
Communication between VIRTEL and CICS can be established via APPC, TCP/IP, or Cross-memory. This
section describes communications in Cross-memory (XM) mode using the VIRKIX program on the CICS
side.
2.13.1 Parameters
External name Must match the relay name of a VIRPASS cross-memory interface in VIRKIX.
Remote ident Contains the jobname of the CICS region in which VIRKIX is running. The CICS region
must be in the same MVS system as VIRTEL.
Local ident Must match the eld “Nom de la liaison” specied in the denition of the VIRPASS cross-
memory interface in VIRKIX.
Prex Terminal name prex (see below).
Entry point Leave blank.
Line type XM1
Possible calls Always 3.
Protocol Always VIRPASS.
Window Always 0.
Packet Always 0.
Pad, Tran Always blank.
62 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.13.2 Terminal Denitions
A VIRPASS XM line for communication with VIRKIX uses a single sub-group of terminals dedicated to
outgoing calls. Either explicit or repeated denitions can be used. The terminals are dened as type 3,
compression 2, and the “Possible calls” eld must be set to 2. The “Relay” eld in the terminal denition
must contain the name of the VIRKIX relay which will be activated at connection time. In the case of
incoming X25 calls this relay is dened in the VIRKIX menu “Interface X25” – “Appels X25 entrant”. The
“Type de line” eld in the relay denition must contain the value X25VIRPA (this is the same value as for
VIRPASS TCP, which was coded as E25TCPIP in previous versions of VIRKIX).
Unlike other terminal types, the relay name specied here is not the name of a VTAM LU.
Terminals on a VIRPASS XM line for VIRKIX
A VIRPASS cross-memory connection is dened in VIRKIX by means of an entity known as a “Virpass
cross-memory interface”:
KIXADMIN -Virpass Cross-Memory ---------- V2R5 -30/06/2005 -10:54:55
Sysid CICS: CICT
Nom interface XM: VIRTELXM
------------------------------------------------------------------------------
Nom du job partenaire : SPTSABYV
Nom de la liaison : XM44000
------------------------------------------------------------------------------
Autres définitions:
Lancement : A M:Manuel A:Autom,évt dans SYSID:
Nbr maxi de connexions: 0010 de 01 à1024
Transaction associée : APIW APIW par défaut
Trace et Snap : O O:Oui N:Non
Trace Connexion : O O:Oui N:Non
Snap centralisé : O O:Oui N:Non
Priorité : 080 de 000 à255
------------------------------------------------------------------------------
2.13. VIRPASS XM line (VIRKIX) 63
Virtel Connectivity Guide, Release 4.58
P3--------P4--------P5--------P6--------P7--------P8--------P12-------ENTER----
Menu Quitter M.A.J Supprimer Saisir Valider
VIRKIX denitions for a VIRPASS XM connection
Nom interface The name of the VIRPASS cross-memory interface (also known as the relay name or “nom
relais”) must match the “external name” of the VIRPASS XM line in VIRTEL.
Nom du job partenaire Species the jobname of the VIRTEL STC, which must be in the same MVS
system as VIRKIX.
Nom de la liaison Must match the “Local ident” of the VIRPASS XM line in VIRTEL.
Refer to the VIRKIX Conguration documentation for details of the other elds on this panel.
64 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.14 X25 XOT line
An XOT line establishes a connection between VIRTEL and a CISCO router. Across this type of line,
VIRTEL processes incoming and outgoing calls to and from the X25 network. Activation of this type of line
requires the presence of the TCP1 parameter in the VIRTCT.
2.14.1 Parameters
Remote ident IP address of the router followed by the port number 1998.
The address specied here is used by VIRTEL as the destination address for outgoing calls. Incoming
calls are accepted from any IP address, except in the case of XOT lines which share a common IP
address and port (specied in the “Local ident” eld). Such lines only accept calls whose IP source
address matches the router address specied in the “Remote ident” eld. This allows VIRTEL to
allocate incoming calls to the correct XOT line. The parameter UNIQUEP=Y (which can be specied
only in batch denition mode using the VIRCONF utility) allows this check to be enforced regardless
of whether the “Local ident” eld species a shared address.
..note:: Take care to ensure that the router presents the expected address to VIRTEL. You may need
to use the xot-source parameter in the router conguration to ensure that the router presents the
correct IP address to VIRTEL for incoming calls. Example:
x25 route .* xot 10.0.1.1 xot-source loopback0
Local ident The IP address and port number on the VIRTEL side. For details of how to code this eld,
refer to “Local ident” under the heading “Line Parameters”,.
2.14. X25 XOT line 65
Virtel Connectivity Guide, Release 4.58
The port number must be 1998. This port number is xed by the XOT protocol, and the router does
not provide any conguration statement which allows the port number to be altered.
From VIRTEL version 4.24 onwards, multiple XOT lines with the same local IP address and port
number can be dened within a single instance of VIRTEL. As explained above, VIRTEL uses the
router IP address (“Remote ident”) to match calls from a router with the correct XOT line. However,
if multiple instances of VIRTEL are started on a single MVS system, each VIRTEL must have its own
distinct IP address for XOT. The use of VIPA allows multiple IP addresses to be dened within a
single TCP/IP stack (see the IBM manual z/OS Communications Server IP Conguration Guide for
details of VIPA).
Prex Terminal name prex (see below).
Entry Point Not required for this type of line.
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls No special restriction.
Protocol Always XOT.
Window In accordance with the window size for the X25 line specied in the router conguration (see note
below).
Packet In accordance with the packet size for the X25 line specied in the router conguration (see note
below).
Note: VIRTEL will normally use the window size and packet size negotiated with the partner during
call setup. The Window and Packet values specied in the line denition are the default values which
will be used if no values are supplied by the partner in the Call or Call Accepted packets.
Pad Always blank.
Tran Normally blank, unless non-standard ASCII translation is required for special applications.
2.14.2 Terminal Denitions
Press [PF4] at the line denition screen to display the list of terminals associated with an XOT
line. An XOT line uses a single sub-group of type-3 terminals having a common prex (XOTF
in this example). Each terminal may be associated with an application relay dened by a VTAM
APPL statement. The number of terminals dened determines the maximum number of simul-
taneous sessions (or virtual circuits) between the router and VIRTEL.
66 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Denition of terminals associated with an XOT line
Terminal The terminal name must match the prex of the line.
Relais The name of a relay LU must be specied if incoming calls are routed to a type-1 transaction (VTAM
application). The relay LU’s must be dened by APPL statements in a VTAM application major node,
as described below. If all incoming calls are routed to a type-3 transaction (external server), as is the
case for calls routed to a GATE or PCNE application such as CFT or Inter.PEL, no relay is required
on the terminals attached to the XOT line.
Entry point Leave blank.
Terminal Type Always 3.
Compression Always 2.
Possible calls Always 3.
Repeat Number of terminals (virtual circuits) dened.^
2.14.3 VTAM Terminal Denition
When incoming calls are routed to a type-1 transaction (VTAM application), the relay LU’s must
be dened by APPL statements in a VTAM application major node, as shown in the example below:
RXOTF000 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RXOTF001 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RXOTF002 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
RXOTF003 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGREL
2.14. X25 XOT line 67
Virtel Connectivity Guide, Release 4.58
2.15 X25 VIRPESIT line
A VIRPESIT line establishes a TCP/IP link between VIRTEL and a le transfer application such as CFT.
A VIRPESIT line allows VIRTEL to act as an IP-to-X25 gateway for le transfer sessions using the PESIT
and ETEBAC protocols. File transfer requests arriving via IP on a VIRPESIT line may be routed either
to a local GATE or PCNE application, or to a remote partner via the X25 network. Similarly, le transfer
requests from the X25 network or from local GATE or PCNE applications may be routed to the IP network
via a VIRPESIT line.
The activation of this type of line requires the presence of the TCP1 parameter in the VIRTCT.
2.15.1 Parameters
Remote ident (optional) IP address and port number of the default partner (for outbound calls when the
external server does not specify a partner IP address).
Local ident The IP address and port number on which VIRTEL listens for incoming connections from the
partner application. For details of how to code this eld, refer to “Local ident” under the heading
“Line Parameters”.
Prex Terminal name prex (see below).
Entry Point The default entry point will be used for all incoming calls which do not match any of the rules
of the line.
Entry points for use with VIRPESIT lines are described under the heading “VIRPESIT gateway” in
the “Incoming calls” section of the VIRTEL Technical Documentation.
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls Specify 3 to allow exchanges in both directions.
Protocol Always VIRPESIT.
68 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
By pressing [PF4], the list of terminals associated with the VIRPESIT line will be displayed. A VIRPESIT
line uses a single group of type-3 terminals having a common prex (I001T in this example). The number
of terminals dened determines the number of simultaneous le transfer sessions authorised. The example
below shows a group of 8 VIRPESIT terminals:
2.15.2 Terminal Denitions
Terminal The terminal name must match the prex of the line.
Relay Leave blank.
Entry point Leave blank. The entry point is dened in the line (or in the rules of the line) for this type of
terminal.
Terminal type Always 3.
Compression Always 2.
Possible Calls Always 3.
Repeat The number of terminals dened.
2.15. X25 VIRPESIT line 69
Virtel Connectivity Guide, Release 4.58
2.16 X25 VIRNEOX line
A VIRNEOX line allows VIRTEL to act as a server for communications with application programs over a
TCP/IP connection using a simplied X25-like protocol. Typically the application will be an existing X25
application which has been converted to TCP/IP. The activation of this type of line requires the presence
of the TCP1 parameter in the VIRTCT.
2.16.1 Parameters
Local ident The IP address and port number on which VIRTEL listens for incoming connections from the
partner application. For details of how to code this eld, refer to “Local ident” under the heading
“Line Parameters”.
Prex Terminal name prex (see below).
Entry Point The default entry point will be used for all incoming calls which do not match any of the rules
of the line. Entry points for use with VIRNEOX lines must specify Emulation type $NONE$
Line type One of the TCP/IP protocols dened in the VIRTCT, for example TCP1.
Possible calls Specify 1 to allow inbound calls.
Protocol Always VIRNEOX.
Packet Specify a packet size sucient to contain the largest message sent by either the host or the partner
application.
By pressing [PF4], the list of terminals associated with the VIRNEOX line will be displayed. A
VIRNEOX line uses a single group of type-3 terminals having a common prex (XNE3 in this example).
The number of terminals dened determines the number of simultaneous conversations authorised.
The example below shows a group of 8 VIRNEOX terminals:
70 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.16.2 Terminal Denitions
Terminal The terminal name must match the prex of the line.
Relay Leave blank.
Entry point Leave blank. The entry point is dened in the line (or in the rules of the line) for this type of
terminal.
Terminal type Always 3.
Compression Always 2.
Possible Calls Always 3.
Repeat The number of terminals dened.
2.16. X25 VIRNEOX line 71
Virtel Connectivity Guide, Release 4.58
2.17 X25 GATE Non Fast-Connect (NFC) line
An X25 GATE Non Fast-Connect line establishes a connection between VIRTEL and an X25 line connected
to an IBM 3745 communications controller. Across this type of line, VIRTEL handles incoming and outgoing
calls to and from the X25 network. Activation of this type of line requires the presence of the GATE and
MINITEL parameters in the VIRTCT.
Denition of an X25 GATE non-Fast Connect line
2.17.1 Parameters
Remote ident Name of the MCH LU generated by NPSI.
Local ident Always blank.
Prex Terminal name prex (see below). The terminal names must be identical to the virtual circuit LU
names generated by NPSI.
Entry Point Not required for this type of line.
Line type Always GATE.
Possible calls No special restriction.
Protocol Always blank.
Window Must agree with the NPSI denition.
Packet Must agree with the NPSI denition.
Pad Must agree with the NPSI denition.
Tran Must agree with the NPSI denition.
From VIRTEL version 4.15 onwards, TRAN must be blank if TRAN=EVEN is specied in the NPSI
denition.
72 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
An X25 GATE Non Fast-Connect line uses a single sub-group of terminals dedicated to the management
of sessions between VIRTEL and the switched virtual circuits on the one hand, and between VIRTEL and
the host applications on the other hand. Each terminal is associated with an application relay dened by a
VTAM APPL statement.
The relay name is compulsory for this type of terminal.
2.17.2 Terminal Denitions
Terminal The terminal name must match the virtual circuit LU names generated by the X25.VC macro in
the NPSI.
Relay The application relay is a VTAM LU which represents the VIRTEL side of the session with NPSI
for each virtual circuit. Relay LUs are dened in a VTAM application major node.
Terminal type Always 1.
Compression Always 2.
Possible calls Specify 3 to allow both incoming and outgoing calls.
Repeat The number of virtual circuits dened by NPSI.
2.17.3 VTAM Terminal Denitions
Each Minitel or PC wishing to benet from VIRTEL functionality must be dened in a VTAM switched
major node similar to the one shown below.
VIRTMINI VBUILD TYPE=SWNET
PU01 PU ADDR=01,*
IDBLK=003,*
IDNUM=xxyyy, Note 1*
MAXDATA=4101, Note 2*
2.17. X25 GATE Non Fast-Connect (NFC) line 73
Virtel Connectivity Guide, Release 4.58
MODETAB=MODVIRT, Note 3*
DLOGMOD=DLOGMINI, *
PACING=1,*
VPACING=3,*
PUTYPE=1,*
DISCNT=YES, *
SSCPFM=USSNTO, *
LOGAPPL=vvvvvv Note 4*
MINI1 LU LOCADDR=0,*
TERM=TWX
..note:
The switched major nodes must be defined as shown in the above example.The associated
,→relays must refer to DLOGMODE DLOGREL in the MODVIRT mode table.
Note 1 IDNUM takes the value xxyyy with xx equal to the value of the parameter IDNUMH in the NPSI
X25MCH MACRO; yyy is a hexadecimal value decrementing in steps of 2 from the CVC number
assigned to the LU.
Let us suppose for example that we have a conguration made up of two TRANSPAC lines, L1 and L2,
containing respectively 16 and 8 entries. The Minitels are installed on line L2. The value yyy assigned
to the rst Minitel is X‘030’ ((16 + 8) x 2) in hexadecimal. The values of yyy respectively assigned to
the other Minitels are X‘02E’, X‘02C’, X‘02A’, X‘028’, etc.
Note 2 The value of MAXDATA must not exceed MAXBFRU times UNITSZ, nor must it exceed the NCP
MAXDATA value.
Note 3 The MODVIRT mode table must be placed in an executable module library (VSE) or in a LOADLIB
(MVS, VM) known to VTAM before activation of the switched major node.
Note 4 LOGAPPL takes the value specied in the APPLID TYPE=INITIAL parameter in the VIRTCT.
If both Minitels and PC’s are used simultaneously, the LOGAPPL parameter must be replaced by the
value USSTAB=USSVIRT (the source of this USSTAB is in the VIRTEL SSL for VSE and in the
MACLIB for MVS).
..note:
The LOGAPPL and USSTAB parameters are valid only for non GATE lines. For sites making
,→outgoing calls, from NCP 5.40 onwards, USSTAB and GATE are incompatible, and
,→therefore the USSTAB keyword should be omitted for a switched major node describing
,→type 1 LU’s.
2.17.4 NCP Parameters
The LUDRPOOL MACRO must contain an NUMTYP1 parameter with a value greater than or equal to
the number of CVC available on the lines. For LU6.2 connections, check for the presence of the NUMILU
parameter which indicates the number of available PU type 2.1.
2.17.5 NPSI Parameters
The following parameters must agree with the specication of your TRANSPAC subscription.
Macro X25VCCPT
74 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
MAXPKTL (packet length) Must equal the value given for “Packet Size” on your TRANSPAC sub-
scription (usually 128).
VWINDOW (packet level window size) Must equal the value given for “Packet Window Size” on your
TRANSPAC subscription (usually 3).
Macro X25MCH
CONNECT Must be specied as NO.
GATE Must be specied as GENERAL.
LLCLIST Must have the value LLC4. LLC0,LLC2,LLC3,LLC4 and LLC5 can for example take the values
0, 2, 3, 4 et 5. Only the value assigned to the LLC4 parameter is important, because it will be appended
to the TRANSPAC number allowing access to the server.
MWINDOW (frame level window size) Must equal the value given for “Frame Window Size” on your
TRANSPAC subscription (usually 7).
FRMLENGTH Must equal MAXPKTL + 3 (usually 131).
PAD Permissible values are NO, INTEG or TRANSP. If the value is INTEG, support for DARK (invisible
elds) is not provided on Minitels in 80 column mode. It is provided where PAD=TRANSP.
In GATE mode, VIRTEL supports DARK in 80 column mode whatever the value of the PAD param-
eter.
SUBADDR Must be YES.
TRAN Must be EVEN or NO.
2.17.6 Routing on incoming calls
Incoming calls are routed by means of an entry point name specied in the Call User Data of the incoming
call packet. If no Call User Data is specied, the value specied in the “Entry Point” parameter of the
terminal denition is used. If this eld is not supplied, the second value of the DEFENTR parameter in the
VIRTCT is used.
Other possibilities are available through the use of a type 1 user exit.
While the sharing of a line in Fast-Connect mode would give better performance, it may prove necessary to
use another method if, for example, the line is used for 3174 connections, or by another product which does
not support Fast-Connect. Except for the denition of the line itself, the remainder of the conguration is
similar to that of a non- shared GATE line. Be aware, however, that the implementation of such a solution
can be complex.
To be able to support line sharing without Fast-Connect mode, the line must be dened as GATE=GEN-
ERAL and the X25MCH CONNECT parameter must be set to NO. The parameters SUBADDR, CTCP
and CUD0 dene the routing of connections and the use of the associated QLLC’s.
X25.MCH RESS=003,*
FRMLENGTH=131,*
LUNAME=(XU01,XU02), LU MCH (Application x, VIRTEL) *
LCGDEF=(0,19), *
MWINDOW=3,*
ANS=CONT, *
DBIT=NO, *
GATE=GENERAL, *
CONNECT=NO, Multi applications without F-C*
CTCP=(00,01), Reference CTCP *
CUD0=(09,01), *
2.17. X25 GATE Non Fast-Connect (NFC) line 75
Virtel Connectivity Guide, Release 4.58
*Calls with subaddr 9connect the terminal to the application
*controlling line XU01 (CTCP=00)
*Calls with subaddr 1connect the terminal to the application
*VIRTEL controlling line XU02 (CTCP=01)
LLCLIST=(LLC0,LLC4,LLCn,...), *
LOGAPPL=(PELC00,VIRTEL), *
SUBADDR=YES, *
IDBLKC=62, Idblk for PCNE (LLC0) *
IDBLKG=63, Idblk for GATE (LLC4) *
*In VTAM there are 2switched major nodes with the same IDNUM
*but different IDBLK (062 for the first, 063 for VIRTEL)
PAD=INTEG, *
PKTMODL=8,*
STATION=DTE, *
SPPED=19200,*
TRAN=EVEN
X25.LCG LCGN=0
X25.VC LCN=(0,19), 20 physical CVC *
TYPE=SWITCHED, *
MAXDATA=4101, Largest VTAM message size *
VCCINDX=1,*
CALL=INOUT Incoming and outgoing calls
..note:
Each application can potentially use up to 20 CVC’s. It is not possible to limit the
,→number of circuits which can be used by each application, as can be done with Fast-
,→Connect.
76 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.18 X25 GATE Fast-Connect (FastC) line
An X25 GATE Fast-Connect line establishes a connection between VIRTEL and an X25 line connected to
an IBM 3745 communications controller. Across this type of line, VIRTEL handles incoming and outgoing
calls to and from the X25 network. Activation of this type of line requires the presence of the FASTC, GATE
and MINITEL parameters in the VIRTCT.
2.18.1 Parameters
Remote ident Name of the MCH LU generated by NPSI.
Local ident Always blank.
Prex An X25 GATE Fast-Connect line uses a single sub-group of terminals dedicated to the management
of sessions between VIRTEL and the switched virtual circuits on the one hand, and between VIRTEL
and the host applications on the other hand. Each terminal is associated with an application relay
dened by a VTAM APPL statement.
Entry Point Not required for this type of line.
Line type Always FASTC.
Possible calls No special restriction.
Protocol Always blank.
Window Must agree with the NPSI denition.
Packet Must agree with the NPSI denition.
Pad Must agree with the NPSI denition.
Tran Must agree with the NPSI denition.
2.18. X25 GATE Fast-Connect (FastC) line 77
Virtel Connectivity Guide, Release 4.58
Terminals on a X25 GATE Fast-Connect line
An X25 GATE Fast-Connect line uses a single sub-group of terminals dedicated to the management of
sessions between VIRTEL and the switched virtual circuits on the one hand, and between VIRTEL and the
host applications on the other hand. Each terminal is associated with an application relay dened by a
VTAM APPL statement.
The relay name is compulsory for this type of terminal.
2.18.2 Terminal Denitions
Terminal The terminal name must match the virtual circuit LU names generated by the X25.VC macro in
the NPSI.
Relay The application relay is a VTAM LU which represents the VIRTEL side of the session with NPSI
for each virtual circuit. Relay LUs are dened in a VTAM application major node.
Terminal type Always 1.
Compression Always 2.
Possible calls Specify 3 to allow both incoming and outgoing calls.
Repeat The number of virtual circuits dened by NPSI.
2.18.3 VTAM Terminal Denitions
Each Minitel or PC wishing to take advantage of VIRTEL functionality must be dened to VTAM in a
switched major node similar to that shown in section “Denition of a X25 GATE Non Fast-Connect line”.
78 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.18.4 NCP/NPSI Denitions
As well as oering a noticable performance improvement, the use of Fast-Connect allows one line to be
shared between several CTCP’s. When the Fast-Connect option is used, there is no VTAM switched major
node. The switched virtual circuit is directly connected to the CTCP. This permanent connection minimizes
connection time as well as the consumption of memory and CPU resources.
The denition of a Fast-Connect line is similar to that of a GATE line, apart from:
Macro X25MCH
CONNECT Must have a value other than NO. The remaining parameters depend on the value of the
CONNECT parameter.
LLCLIST Must contain the value LLC5.
2.18.5 Sharing of FastC lines
X25.MCH ADRESS=003,*
FRMLENGTH=131,*
LUNAME=(XU01,XU02), LU associated with each VIRTEL *
LCGDEF=(0,19), *
MWINDOW=3,*
ANS=CONT, *
DBIT=NO, *
GATE=GENERAL, *
CONNECT=SUBD, F-C to multiple VIRTEL *
SUBD=(4,9,1), Subaddresses 4,9,1*
CTCP=(0,1,1)1st VIRTEL if 4,*
2nd VIRTEL if 9or 1*
LOGAPPL=(VIRTEL1,VIRTEL2) Applid of each VIRTEL *
LLCLIST=(LLC4) *
SUBADDR=NO, *
PAD=NO, *
PKTMODL=8,*
STATION=DTE, *
SPEED=19200,*
TRAN=NO
X25.LCG LCGN=0
X25.VC LCN=(0,19), 20 physical CVC *
TYPE=SWITCHED, *
MAXDATA=4101, Largest VTAM message size *
VCCINDX=1,*
CALL=INOUT Incoming and outgoing calls
X25.FCG QTY=(15), No.of CVC used for CTCP 0*
CTCPNO=(0), CTCP number *
ANS=CONT, *
MAXDATA=4101,*
PRFLINE=XU01, Line name prefix *
PRFPU=XP01, PU name prefix *
PRFLU=XL01, Virtual LU name prefix *
SUFFIX=0001 LU numbers incremented by 1
X25.FCG QTY=(15), No of CVC used for CTCP 1*
CTCPNO=(1), CTCP number *
ANS=CONT, *
MAXDATA=4101,*
PRFLINE=XU02, Line name prefix *
PRFPU=XP02, PU name prefix *
2.18. X25 GATE Fast-Connect (FastC) line 79
Virtel Connectivity Guide, Release 4.58
PRFLU=XL02, Virtual LU name prefix *
SUFFIX=0001 LU numbers incremented by 1
Example of a Fast-Connect line shared between 2 VIRTELs using subaddressing
..note:
The number of “logical” virtual circuits can be greater than the number of “physical”
,→virtual circuits. This example has 20 physical virtual circuits for 30 (2 X 15)
,→logical virtual circuits.
X25.MCH ADRESS=003,*
FRMLENGTH=131,*
LUNAME=XU01, MCH LU associated with VIRTEL *
LCGDEF=(0,19), *
MWINDOW=3,*
ANS=CONT, *
DBIT=NO, *
GATE=GENERAL, *
CONNECT=YES, F-C to multiple VIRTEL *
LOGAPPL=VIRTEL1, Applid of VIRTEL *
LLCLIST=LLC4, *
SUBD=NO, SUBD=NO *
PAD=NO, *
PKTMODL=8,*
STATION=DTE, *
SPPED=19200,*
TRAN=NO
X25.LCG LCGN=0
X25.VC LCN=(0,19), 20 physical CVC *
TYPE=SWITCHED, *
MAXDATA=4101, Largest VTAM message size *
PRFLINE=ZL01, *
PRFPU=ZPU01, *
PRFLU=ZLU01, *
VCCINDX=1,*
CALL=INOUT Incoming and outgoing calls
Example of a Fast-Connect line with a single CTCP without subaddressing
80 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.19 X25 AntiGATE line
A Reverse-X25 AntiGATE line establishes a link between VIRTEL and a Communication and Transmission
Control Program (CTCP) application. On this type of line, VIRTEL communicates with the CTCP to
manage incoming and outgoing calls to and from the X25 network. Once a virtual circuit is established, data
ows across LU-LU sessions between the VIRTEL terminals and the CTCP. In this way, VIRTEL emulates
an IBM 3745 controller with NPSI.
2.19.1 Parameters
Remote ident LU name of the CTCP (CFT, Inter.PEL, etc). May be blank if WAIT-PARTNER is coded
in the “Startup pre-requisite” eld.
Local ident Name of the LU which represents the physical circuit for the AntiGATE line (analogous to
the LU generated by the NPSI X25.MCH macro in the NCP). This LU must be dened by a VTAM
APPL statement.
Prex Terminal name prex (see below).
Entry Point The default entry point, if no entry point is dened at the terminal level, or in the line rules
or call user data.
Line type Always /GATE.
Possible calls No special restriction.
Startup prerequisite WAIT-PARTNER is recommended for AntiGATE lines. WAIT-PARTNER must
be specied if the partner is CFT.
Protocol Always blank.
Window, Packet Must agree with the denition in the CTCP.
Pad, Tran Must agree with the denition in the CTCP.
2.19. X25 AntiGATE line 81
Virtel Connectivity Guide, Release 4.58
2.19.2 Terminal Denitions
An AntiGATE line uses a single sub-group of terminals which represent the virtual circuits allocated to
the line (analogous to the LU’s linked to the virtual circuits dened by the NPSI macro X25.VC in the
NCP). The terminal name is an internal name which is used to associate the terminal denition with the
AntiGATE line. The associated relay name must match the name of a VTAM APPL statement. Either
explicit or repeated terminal denitions may be used.
Terminals on an X25 AntiGATE line
2.19.3 VTAM Terminal Denitions
The The LU’s representing the line and the virtual circuits must be dened by APPL statements in a VTAM
application major node similar to the following example:
VIRAGATE VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
*Pseudo ligne gate émulée par Virtel (note 1)*
* ------------------------------------------------------------------ *
VXU21 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
* ------------------------------------------------------------------ *
*Pseudo cvcs pour ligne gate émulée par Virtel (note 1)*
* ------------------------------------------------------------------ *
AG21LU01 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
AG21LU02 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
AG21LU03 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
AG21LU04 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
...
VTAM denitions for an X25 AntiGATE line
Note 1 The LU’s dened in the “Local ident” eld of the line must specify logmode DLOGANTI.
82 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Note 2 The LU’s for the terminal relays can use a logmode appropriate for the application.
Note 3 The MODVIRT phase must be placed in an executable library (VSE) or in a LOADLIB (MVS,
VM) dened to VTAM before the application major node can be activated.
2.19. X25 AntiGATE line 83
Virtel Connectivity Guide, Release 4.58
2.20 X25 Anti Fast Connect (FastC) line
Similar to an AntiGATE line, a Reverse-X25 AntiFastC line establishes a link between VIRTEL and a
Communication and Transmission Control Program (CTCP) application. On this type of line, VIRTEL
communicates with the CTCP to manage incoming and outgoing calls to and from the X25 network. Once
a virtual circuit is established, data ows across LU-LU sessions between the VIRTEL terminals and the
CTCP. In this way, VIRTEL emulates an IBM 3745 controller with NPSI.
2.20.1 Parameters
Remote ident CTCP LU name.
Local ident Name of the LU which represents the physical circuit for the AntiFastC line (analogous to the
LU generated by the NPSI X25.MCH macro in the NCP). This LU must be dened by a VTAM APPL
statement.
Prex Terminal name prex (see below).
Entry Point The default entry point, if no entry point is dened at the terminal level, or in the line rules
or call user data.
Line type Always /FASTC.
Possible calls No special restriction.
Protocol Always blank.
Window, Packet Must agree with the denition in the CTCP.
Pad Must agree with the denition in the CTCP.
Tran Specify EVEN, ODD, or NO according to the requirements of the CTCP. Additionally, for AntiFastC
lines only: the special value EBCD indicates that VIRTEL will perform the necessary conversion to
allow a Videotex server CTCP to be accessed in 3270 mode (VIRTEL Multisession or Web Access).
84 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.20.2 Terminal Denitions
An AntiFastC link uses a single sub-group of terminals which represent the virtual circuits allocated to the
line (analogous to the LU’s linked to the virtual circuits dened by the NPSI macro X25.VC in the NCP).
The terminal name is an internal name which is used to associate the terminal denition with the AntiFastC
line. The associated relay name must match the name of a VTAM APPL statement. Either explicit or
repeated terminal denitions may be used.
Terminals on an X25 AntiFastC line
The LU’s representing the line and the virtual circuits must be dened by APPL statements in a VTAM
application major node similar to the following example:
VIRAFAST VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
*Pseudo ligne fastc émulée par Virtel (note 1)*
* ------------------------------------------------------------------ *
VXU14 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
* ------------------------------------------------------------------ *
*Pseudo cvcs pour ligne fastc émulée par Virtel (note 1)*
* ------------------------------------------------------------------ *
X25AF500 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
X25AF501 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
X25AF502 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
X25AF503 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGANTI
2.20.3 VTAM Terminal Denitions
Note 1 The LU’s dened in the “Local ident” eld of the line must specify logmode DLOGANTI.
Note 2 The LU’s for the terminal relays can use a logmode appropriate for the application.
Note 3 The MODVIRT phase must be placed in an executable library (VSE) or in a LOADLIB (MVS,
VM) dened to VTAM before the application major node can be activated.
2.20. X25 Anti Fast Connect (FastC) line 85
Virtel Connectivity Guide, Release 4.58
2.21 X25 AntiPCNE line
Like an AntiGATE or AntiFastC line, a Reverse-X25 AntiPCNE line establishes a link between VIRTEL
and an application. By contrast however, VIRTEL does not use a line-level LU to manage call setup, and
the application does not supply VIRTEL with a call packet. Instead, the application makes outgoing calls
by choosing a particular LU associated with the AntiPCNE line. The X25 called number is dened at the
terminal level by means of an associated external server denition. In this way, VIRTEL emulates an IBM
3745 controller with NPSI.
2.21.1 Parameters
Remote ident Partner application LU name.
Local ident Always blank.
Prex Terminal name prex (see below).
Entry Point Leave blank. The entry point should be dened in the rules of the line.
Line type Always /PCNE.
Possible calls No special restriction.
Protocol Always blank.
Window Not used for an AntiPCNE line.
Packet Not used for an AntiPCNE line.
Pad Always NO.
Tran Always NO.
86 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.21.2 Terminal Denitions
An AntiPCNE line uses two sub-groups of terminals. In each case, the terminal name is an internal name
which is used to associate the terminal denition with the AntiPCNE line. The associated relay name must
match the name of a VTAM APPL statement.
The rst sub-group is used for outgoing calls (from the point of view of the application), and consists of
explicitly dened terminals with the “Possible calls” eld set to 1. Each terminal in this rst sub-group
corresponds to a single remote partner. The “Relay” eld of each terminal in this rst sub-group must
contain the LU name which the application uses to make outgoing calls to the remote partner concerned.
The entry point specied by the rules of the line contains a type-3 transaction which species “&R” as
the application name. This makes the link with an external server whose name is identical to the Relay
LU name. The external server contains the call parameters (X25 number, etc) needed to route calls to the
required partner.
The example below shows the denition of an AntiPCNE terminal for outbound calls made using LU name
AP1LU01O, and the associated external server containing the X25 call parameters:
Outbound Terminal Denition for X25 AntiPCNE
2.21. X25 AntiPCNE line 87
Virtel Connectivity Guide, Release 4.58
External server denition for X25 AntiPCNE
The second sub-group is used for incoming calls (from the point of view of the application). In this sub-
group, the “Possible calls” eld is set to 2. Either explicit or repeated terminal denitions may be used for
this second sub-group, and no entry point is necessary. Each terminal in the second sub-group can be used
for calls originating from any remote partner. This method is suitable for applications such as CFT which
do not verify the LU name for incoming calls.
Inbound terminal denition for X25 AntiPCNE (method 1)
A second method of dening AntiPCNE terminals allows the administrator to specify the selection of an
88 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
LU name according to the characteristics of the incoming call. This method is suitable for applications such
as Inter.PEL which require incoming calls to arrive on specic LU names according to the identity of the
partner which originated the call. In this case, the terminals in the second sub-group specify the name of
a logical pool instead of a relay LU name (see “logical pool of relays”). The terminals in the logical pool
contain the relay LU’s. The selection of an LU is done by means of the rule which routes the incoming call,
by specifying the required LU name in the “Parameter” eld of the rule. Note that the rules which route
incoming calls are those attached to the line on which the call arrives (for example, an XOT line) and not
those attached to the AntiPCNE line.
The example below shows the denition of a set of inbound terminals (PCN1TM51-54) attached to an
AntiPCNE line. These terminals, which are dened using the repeated method, all refer to a logical pool
*POOLPCN. Terminal Denitions PCNETM51-54 are explicitly dened and constitute the logical pool. The
relay names AP30LU51-54 are dened in the logical pool. A set of rules attached to the XOT line on which
incoming calls arrive assigns an LU from the pool to each incoming call according to the contents of the
CUD0 eld in the incoming call packet.
+----------+----------+----------+-------+------+-----+---------+-----------+
|Terminal |Repeated |Relay |Entry |Type |I/O|Pool |2nd Relay |
+==========+==========+==========+=======+======+=====+=========+===========+
|PCNETM51 |0001 |AP30LU51 | | 3|2|*POOLPCN | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCNETM52 |0001 |AP30LU52 | | 3|2|*POOLPCN | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCNETM53 |0001 |AP30LU53 | | 3|2|*POOLPCN | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCNETM54 |0001 |AP30LU54 | | 3|2|*POOLPCN | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCN1TM01 |0000 |AP30LU01 | | 3|1| | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCN1TM02 |0001 |AP30LU02 | | 3|1| | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCN1TM03 |0001 |AP30LU03 | | 3|1| | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCN1TM04 |0001 |AP30LU04 | | 3|1| | |
+----------+----------+----------+-------+------+-----+---------+-----------+
|PCN1TM51 |0004 | *POOLPCN | | 3|2| | |
+----------+----------+----------+-------+------+-----+---------+-----------+
List of inbound terminal denitions for X25 AntiPCNE
2.21. X25 AntiPCNE line 89
Virtel Connectivity Guide, Release 4.58
Inbound terminal denition for X25 AntiPCNE
Logical pool denition for X25 AntiPCNE
90 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
Rule for incoming X25 AntiPCNE calls
2.21.3 VTAM Terminal Denitions
The LU’s representing the line and the virtual circuits must be dened by APPL statements in a VTAM
application major node similar to the following example:
VIRAPCNE VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
* Pseudo cvcs pour ligne pcne émulée par Virtel (note 1) *
* ------------------------------------------------------------------ *
AP30LU01 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU02 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU03 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU04 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU51 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU52 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU53 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
AP30LU54 APPL AUTH=(ACQ,PASS),MODETAB=MODVIRT,DLOGMOD=DLOGPCNE
Note 1
The LU’s for the terminal relays must specify logmode DLOGPCNE.
Note 2
The MODVIRT phase must be placed in an executable library (VSE) or in a LOADLIB
,→(MVS, VM) defined to VTAM before the application major node can be activated.
2.21.4 Add or changing AntiPCNE LU names
From VIRTEL version 4.28 onwards, it is possible to add a new terminal to an AntiPCNE line, or to change
the relay LU name in an existing terminal, without stopping and restarting VIRTEL.
2.21. X25 AntiPCNE line 91
Virtel Connectivity Guide, Release 4.58
The procedure for adding a new AntiPCNE terminal is as follows:
1. For an outbound terminal, add a new terminal denition by pressing [PF12] at the List of Terminals
screen (position the cursor on an existing terminal if desired to copy its denition). Specify the new
terminal name and LU name in the “Terminal” and “Relay” elds, and specify “Terminal type 3”
“Compression 0” and “Possible Calls 1”. Then press [Enter] to add the new denition. While still in
the Terminal Detail Denition screen, press [PF12] to dene a new external server with the same name
as the relay. Fill in the outbound call parameters and press [Enter] to add the new denition.
2. For an inbound terminal, add a new terminal denition as above but with “Possible Calls 2”. Specify
either an LU name or the name of a logical pool in the “Relay” eld. If using a logical pool, also add
a new terminal denition to the logical pool specifying the LU name in the “Relay” eld, and add a
rule to the XOT line to allocate incoming calls to this LU.
3. Dene the new LU name as an APPL statement in a VTAM application major node and activate it.
4. Use the VIRTEL LINE START command to activate the new terminal(s) on the AntiPCNE line. For
example:
:: F VIRTEL,LINE=P-PCNE1,START
The procedure for changing the LU name of an existing AntiPCNE terminal is as follows:
1. Enter the new LU name in the “Relay” eld of the Terminal Detail Denition screen for the terminal
or logical pool concerned, and press [PF1] to record the change.
2. For an outbound terminal, copy the existing external server denition for the old LU name, renaming
it using the new LU name. For an inbound terminal, go to the XOT line denition and alter the rule
(if any) which species the old LU name in its “Parameter” eld, replacing the old LU name by the
new LU name, and press [PF1].
3. Inactivate the existing VTAM LU.
4. Dene the new LU name as an APPL statement in a VTAM application major node and activate it.
5. Use the VIRTEL LINE START command to reactivate the changed terminal(s) on the AntiPCNE line.
For example: F VIRTEL,LINE=P-PCNE1,START
2.21.5 Support of X25 non GATE terminals
Support for incoming connections via an X25 non GATE line still exists. This type of connection does not
require a line denition in VIRTEL. All that is needed is to create a series of terminals using the Terminal
Management sub- application. Each terminal is dened as type 1 compression 2 and is associated with an
application relay.
..note:
This mode allows only incoming calls, with no facility for call routing.
2.21.6 VTAM denitions for X25 non GATE terminals
Each Minitel or PC which is to log on to VIRTEL must be dened in a VTAM switched major node as
described in “Denition of an X25 GATE Non Fast-Connect line”.
92 Chapter 2. Lines
Virtel Connectivity Guide, Release 4.58
2.21.7 NCP/NPSI parameters for X25 non GATE terminals
The information presented in the section “Denition of an X25 GATE Non Fast-Connect line” applies here
with the following addition:
Macro X25.MCH
LLCLIST Must contain the value LLC5.
2.21. X25 AntiPCNE line 93
Virtel Connectivity Guide, Release 4.58
94 Chapter 2. Lines
CHAPTER
THREE
VIRTEL RULES
3.1 Introduction
Each Virtel line can have a set of rules which allow the selection of an entry point for each incoming call
according to the characteristics of the call and the rule criteria. Rules are processed in alphanumeric order
of name, so it is important that the name you choose gaurantees order of the rule processing. As sonn as
a match is found within the denied rule criteria the designated entry point will be assigned to the caller.
Rules are useful to force or nail Virtel Relay LU names or to establish dierent application lists depending
on the incoming IP address. The last rule should be the “default” rule which is used to catch callers that
didn’t match with previous rules. If no default rule is present then the caller will drop through the rule
processing and the connection will be closed. See the “How-To” guide ‘Virtel LU Nailing’ for examples on
how to dene and use Virtel Rules.
3.1.1 Summary Display
Press [PF5] at the line detail denition screen to display the summary list of rules associated with the line:
Rule Summary Display
95
Virtel Connectivity Guide, Release 4.58
Field Contents
Name The name of the rule. Rules associated with a line are processed in alphanumeric order.
Status Indicates whether the rule is ACTIVE or INACTIVE. To change the status, display the detailed
denition of the rule [PF12], then press [PF4] to activate, or [PF5] to inactivate.
Description Free-form description of the rule.
Entry Point Name of the entry point which will be assigned to incoming calls whose characteristics match
this rule.
Navigation
Search Type the name (or partial name) of the required entity on the rst line under the heading “Name”,
then press [Enter].
[PF6] Return to the rst page of the list.
[PF7] Display the previous page.
[PF8] Display the next page.
Modifying a rule - Pressing [PF12] at the Rules screen displays the rule detail denition screen. Type
the desired modications into the appropriate elds then press [PF1]. Multiple denitions can be modied
at the same time. If the modication aects a eld not displayed on the summary screen, rst position the
cursor on the denition concerned, then press [PF12] to access the denition detail screen.
..warning:: Modications are not recognized until you press the [PF1] key. Certain modications require a
restart of the VIRTEL system.
Deleting a rule - In the summary screen position the cursor under the name of the entity to be deleted,
then press [PF2]. The line associated with the entity to be deleted then appears highlighted, accompanied
by the message CONFIRM DELETE. Then press [PF2] again to conrm deletion. The message DELETE
OK conrms successful completion of the operation. Repeat the procedure for each entity to be deleted.
Adding a rule - To add a new denition, press [PF12] at the summary screen, either with the cursor on an
existing denition to copy its attributes, or on an empty line to create a new denition from a blank screen.
3.1.2 Detail Display
To display or update the detailed denition of an entity, place the cursor on the name of the entity within
the summary display and press [PF12]. The detail denition screen will then be displayed.
96 Chapter 3. Virtel Rules
Virtel Connectivity Guide, Release 4.58
Rule detail denition screen
3.1.3 Parameters
Name The name of the rule. This name must be unique across all rules in the system. The rules associated
with a line are processed in alphanumeric order of this name. The rule name thus determines the
priority of the rule within the line.
Status Indicates whether the rule is ACTIVE or INACTIVE. To activate a rule, press [PF4]. To inactivate
a rule, press [PF5].
Description Description of the rule. This information is not used.
Entry point The name of the entry point which will be assigned to the incoming call if this rule matches
the call characteristics.
Note: The value $COOKIE$ in the “Entry Point” eld has a special meaning. This value is meaningful
only in rules attached to an HTTP line. If a rule with this value is found, and if the HTTP request contains
a cookie named VirtelRef, then the value of the cookie is used to identify the user, and VIRTEL switches to
the rule set associated with the user, instead of processing the remainder of the rules attached to the line. If
the HTTP request does not contain a cookie named VirtelRef, VIRTEL ignores this rule, and continues with
the next rule attached to the line. See “Correspondent management” in the VIRTEL Web Access Guide.
Parameter (optional) A parameter which will be associated with incoming calls matched by this rule. This
parameter can be used in the following cases:
• the value of the parameter can be retrieved in a connection script via the ‘&1’ variable (see
“Connection – Disconnection Scripts”)
• For an XOT line: the parameter can specify the LU name for an incoming PCNE call. The
terminals on the AntiPCNE line to which the call is routed must be dened in a logical pool (see
“Terminals on an AntiPCNE line”)
3.1. Introduction 97
Virtel Connectivity Guide, Release 4.58
• For an HTTP line: the parameter can specify the LU name to be used as the VTAM relay for
an incoming HTTP call. The relay terminals on the HTTP line must be dened in a logical pool
(see “Terminals on an HTTP line”).
An asterisk at the end of the LU name signies that the parameter is a prex rather than a specic value.
For an HTTP line: The value $URL$ in the “Parameter” eld indicates that the actual parameter value will
be obtained from the userdata eld of the URL (see “VIRTEL URL formats” in the VIRTEL Web Access
Guide).
Note: The value $COOKIE$ in the “Parameter” eld has a special meaning. This value is meaningful
only in rules attached to an HTTP line. If a rule with this value is found, and if the HTTP request contains
a cookie named VirtelRef, and the value of the cookie matches a record in the VIRTEL correspondent le
(see “Correspondent management” in the VIRTEL Web Access Guide), then VIRTEL selects this rule and
uses the VTAM LU name contained in the correspondent record as the VTAM relay for the incoming HTTP
call. If the HTTP request does not contain a cookie named VirtelRef, or if the value of the cookie does not
match any user in the correspondent le, then VIRTEL ignores this rule, and continues with the next rule
attached to the line.
Trace Trace indicator for incoming calls which match this rule.
Blank No trace.
1Trace X25 commands.
2Trace X25 data.
12 Trace X25 commands + data.
123 Where the call is rerouted via an external server, the trace will also be applied on the line used
for the outgoing call.
Note: Each of the following elds is preceded by a comparison indicator. The comparison indicator can be
0 (ignore), 1 (must equal), 2 (must not equal), 3 (must begin with), 4 (must not begin with), 5 (must end
with), or 6 (must not end with). An incoming call matches this rule if all of the elds (except those whose
comparison indicator is 0) match the corresponding characteristic of the call. A rule with all its comparison
indicators set to 0 is an unconditional rule, which matches all incoming calls not matched by a higher priority
rule.
IP Subnet For an HTTP or SMTP line: The originating IP address or subnet address.
Mask Indicates which bit positions in the IP address form the subnet address. For example, IP ad-
dress 192.168.210.0 combined with mask 255.255.255.0 corresponds to addresses 192.168.210.0 through
192.168.210.255.
HTTP Host For an HTTP line: The host name (possibly followed by a port number) supplied by the
browser in the Host: HTTP header when connecting to VIRTEL.
For example, www.virtel.com:21000
In the case of requests forwarded by a reverse proxy (bastion host), the rule compares the value of this
eld with the X-Forwarded-Host: header (if present) instead of the Host: header.
For an SMTP line: The recipient’s email address.
eMail For an SMTP line: The sender’s email address.
Calling DTE For an X25 line: The calling number specied in the X25 call packet.
98 Chapter 3. Virtel Rules
Virtel Connectivity Guide, Release 4.58
For an HTTP line: The IP address of the reverse proxy (bastion host) which forwarded the request on
behalf of the originating user. If this eld is present in the rule, and matches the source IP address of the
HTTP request, then a “forwarding header” (see below) in the HTTP request is considered to contain
the real originating IP address. This real originating IP address will be the one used for testing against
the “IP Subnet” and “Mask” elds (if any) in the rule. If the rule matches, then message VIRHT56I
will be issued and the call will henceforth be considered to have originated from the real originating
IP address for the purposes of console messages and VIRLOG.
VIRTEL recognizes the following “forwarding headers” (in order of priority):
• iv-remote-address:
• X-Forwarded-For:
Note: When the “Calling DTE” eld contains an IP address, leading zeroes must be included where
necessary. For example, 192.168.001.020
Reverse proxy addresses may also be specied in the HTFORWD parameter of the VIRTCT (see
“Parameters of the VIRTCT” in the VIRTEL Installation Guide).
Called For an X25 line: The called number specied in the X25 call packet. CUD0 (Hex)For an X25 line:
Up to 8 hexadecimal digits representing the rst 4 bytes of the CUD eld of the X25 call packet. For
example, 01000000 (PAD), C0123450 (PCNE), C4 (GATE).
User Data For an X25 line: The remaining part of the CUD (call user data) in the X25 call packet. The
data in this eld is expressed in character format. It is compared with the ASCII data starting at the
5th byte of the CUD eld in the X25 call packet. VIRTEL performs the necessary ASCII-EBCDIC
translation prior to comparing the contents of this eld. To test the rst 4 bytes of the CUD, use
the CUD0 eld in the rule instead. Example: a call packet whose “Call User Data” eld contains:
C0123450 41424331 matches a rule which species CUD0=C0123450 and UserData=ABC1. For an
HTTP line: The contents of the userdata eld of the URL (see “VIRTEL URL formats” in the VIRTEL
Web Access Guide).
Note: The following elds indicate the time periods during which this rule is active. The comparison
indicator can be 0, 1, or 2.
Days The days of the week on which this rule applies. Applicable days are marked by an ‘X’.
Start Time / End Time Indicates the period of operation of this rule for each applicable day.
3.1. Introduction 99
Virtel Connectivity Guide, Release 4.58
100 Chapter 3. Virtel Rules
CHAPTER
FOUR
TERMINALS
4.1 Introduction
All terminals, whether physical or virtual, using the services of VIRTEL must be referenced. This chapter
describes the group of functions associated with the management of the terminals as well as their existing
relationship to other administration functions, for example, management of lines or entry points.
4.1.1 Terminal Management Sub-Application
This sub-application enables the denition of VIRTEL terminals either in the form of a pool, or individually.
When the sub-application is started, it rst presents a summary of existing terminal denitions presented
in alphanumeric order.
The terminal management sub-application is accessed by pressing [PF2] in the Conguration Menu, or
[PF5] in the Sub Application Menu, or from the Multi-session Menu via a transaction referencing module
VIR0023. This sub-application allows for the management of the parameters associated with each terminal
under control of VIRTEL. This subapplication is also accessible by pressing [PF4] from the line management
sub-application.
4.1.2 Security
When security is active, access to the terminal management menu from the Conguration Menu or the Sub-
Application Menu is controlled by the resource $$TERM$$. When this menu is accessed via a transaction,
the rules governing the security management of transactions will apply. Security management is described
in chapter 4 of the VIRTEL Technical Documentation.
4.1.3 Summary Display
The rst screen displayed by the terminal management sub-application shows a summary of existing deni-
tions in alphanumeric order. A complete description of each eld is given in the following paragraphs. Place
the cursor under an entry a press [PF12] to display the terminal details.
101
Virtel Connectivity Guide, Release 4.58
Terminal Summary Display
Navigation
In browse, alter, or delete mode, it is possible to scroll the list of terminals under the control of VIRTEL.
Search Type the name (or partial name) of the required entity on the rst line under the heading “Terminal”,
then press [Enter].
[PF6] Return to the rst page of the list.
[PF7] Display the previous page.
[PF8] Display the next page.
Modifying a terminal entry - Pressing [PF12] at the summary screen displays the Terminal Detail
Denition screen, which allows creation of a new terminal denition, or modication of an existing denition.
Type the desired modications into the appropriate elds then press [PF1]. Multiple denitions can be
modied at the same time. If the modication aects a eld not displayed on the summary screen, rst
position the cursor on the denition concerned, then press [PF12] to access the denition detail screen.
Modications are not recognized until you press the [PF1] key. Certain modications require a restart of the
VIRTEL system.
Adding a terminal entry - To add a new denition, press [PF12] at the summary screen, either with the
cursor on an existing denition to copy its attributes, or on an empty line to create a new denition.
Deleting a terminal entry - Position the cursor under the name of the entry to be deleted, then press
[PF2]. The line associated with the terminal to be deleted then appears highlighted, accompanied by the
message CONFIRM DELETE. Then press [PF2] again to conrm deletion. The message DELETE OK
conrms successful completion of the operation. Repeat the procedure for each entry to be deleted.
102 Chapter 4. Terminals
Virtel Connectivity Guide, Release 4.58
4.1.4 Detail Display
Terminal Denition detail screen
From within the detail display parameters can be updated.
4.1.5 Parameters
Terminal Maximum of 8 characters containing:
• For a 3270 terminal which logs on to the VIRTEL application: The VTAM-dened LU
name of the terminal
• For an LU which connects to VIRTEL via a GATE or FASTC line: The NPSI-dened
LU name, whose prex associates the terminal with the VIRTEL GATE or FASTC line
• For all other types of terminal: An internal name whose prex associates the terminal
with a VIRTEL line.
• For a logical pool: An internal name of no signicance.
• For a physical pool: A sequence of 8 characters starting with “?” (see “Physical pool of
terminals”).
If the “Repeat” eld contains a value greater than 1, then the terminal name must contain a
numeric portion which will be incremented for each occurrence of the terminal (see “Repeat”
parameter below).
Relay (Optional) The name of the relay LU associated with this terminal. The relay name corresponds to
a VTAM APPL statement. The same relay cannot be shared between multiple denitions.
The “Relay” eld may alternatively contain a name in the form *POOLNAM which refers to the logical
pool which has the same name *POOLNAM specied in its “*Pool name” eld. In this case, a relay
will be assigned dynamically from the specied logical pool each time a relay is required. See “logical
pool of relays”. Certain terminals (those associated with an AntiPCNE line) require the denition of
4.1. Introduction 103
Virtel Connectivity Guide, Release 4.58
an external server whose name is equal to the relay name of the terminal. In this case, you can press
[PF12] to display the external server detail denition. If the “Repeat” eld contains a value greater
than 1, then the relay name, if supplied, must contain a numeric portion which will be incremented
for each occurrence of the terminal (see “Repeat” parameter below), or it must refer to a logical pool.
If SYSPLUS=YES is specied (see “Parameters of the VIRTCT” in the VIRTEL Installation Guide),
any ‘+’ character in the relay name will be replaced by the value of the SYSCLONE system symbol.
SYSCLONE is specied in the IEASYMxx member of SYS1.PARMLIB, and identies the particular
LPAR that VIRTEL is running on in a sysplex environment.
Terminal Denition records in the VIRARBO le whose repeat count is greater than 1 may now contain
special pattern characters in the “terminal name”, “relay”, and “2nd relay” elds. Multiple instances
of the terminal will be generated at Virtel startup by incrementing the pattern characters according
to the rules shown below. If a name contains no pattern characters then Virtel will increment the
rightmost numeric portion of the name, as before.
Pattern characters:
> Alphabetic A-Z
? Alphanumeric A-Z, 0-9, $, #, @
% Hexadecimal digits 0-9, A-F
< Decimal digits 0-9
Note: Dierent combinations of pattern characters may be specied within a single eld, for example
RH>VT?%% the terminal name and relay names do not have to follow the same pattern (see example
below). The ‘?’ character cannot be used in the rst character position of the terminal name eld because
this indicates a physical pool
Example:-
Terminal name W2HVT000
Relay name RHTERM%%
Relay2 name RH>X<Z00
Repeat count 256
Would generate terminals W2HVT000-W2HVT255 with relay names RHTERM00-RHTERMFF and relay2
names RHAX0Z00-RHIX5Z00
*Pool name In the denition of a logical pool, this eld contains the name of the pool. A logical pool name
is a 7 character name preceded by an asterisk, in the form *POOLNAM, which matches the logical
pool name specied in the “Relay” eld of all terminals which use the logical pool. See “logical pool
of relays”. For regular terminals, this eld must be blank.
Description Free-format eld.
Entry Point An optional eld which may contains the name of the associated entry point. For details of
how VIRTEL uses this eld, see “Choosing the Entry Point”. It is only useful to specify the entry point
at the terminal level in the following cases:
• 3270 terminals
• Asynchronous terminals on X25 non-GATE lines.Since this type of terminal is not associated
with a VIRTEL line, it may be useful to specify a default entry point at the terminal level. This
overrides the default dened by the DEFENTR parameter in the VIRTCT.
• Terminals on VIRNT or VIRKIX lines in APPC mode. If the link between the NT or CICS system
and VIRTEL is of type APPC2, the terminal must specify entry point $X25$ (for a connection
with VIRNT) or VAPI (for a connection with VIRKIX). It is not necessary to create entry point
denitions for these special names, as they are entry points implicitly dened by VIRTEL.
104 Chapter 4. Terminals
Virtel Connectivity Guide, Release 4.58
• Type P or S printer terminals on HTTP lines.This type of printer will be automatically connected
to the host application dened by the rst transaction under the specied entry point.
In all other cases, the “Entry Point” eld in the terminal denition should be blank, as the preferred
method of dening the entry point is by the rules of the line (see “Rules”). Rules have the advantage
that they can be altered dynamically, while allowing more exibility in the selection of the entry point
according to the characteristics of the incoming call.
2nd Relay Contains the name of a relay associated with an virtual printer simulated by VIRTEL. Each of
these relays corresponds to an APPL statement known to VTAM. This virtual printer must be dened
in VIRTEL in the form of a terminal of type 1, 2, P, or S.
This eld must only be completed for type 1 or type 3 terminals.
If the “Repeat” eld contains a value greater than 1, then the 2nd relay name, if supplied, must
contain a numeric portion which will be incremented for each occurrence of the terminal (see “Repeat”
parameter below).
Terminal type Indicates the type of terminal. Permissible values are:
1for an asynchronous Non Fast-Connect terminal (Minitel, PC or VT) or a pseudo-printer of type
SCS (LUTYPE1)
2for a 3270 synchronous terminal (LUTYPE2) or a pseudo-printer of type 3270 (LUTYPE3)
3for all terminals other than type 1 and 2
Pfor a virtual printer of type 3270 (LUTYPE3) with auto-connection to the application dened by
the “Entry Point” eld
Sfor a virtual printer of type SCS (LUTYPE1) with auto-connection to the application dened by
the “Entry Point” eld
The concept of an APPC connection now being at the line level, denitions of type 6 no longer exist
at the terminal level.
Compression Indicates the optimization mode applicable during transmission of 3270 messages towards
the terminal. Permissible values are:
0no optimisation. No message compression is performed by VIRTEL. This value is usually used at
sites which only use VIRTEL Multi-Session or le-transfer terminals. This value is only allowed
for type 2 terminals.
1simple message optimisation. Replacement of repeated characters by Repeat-to-Address orders,
allowing a throughput gain of approximately 30%. This value could for example be used for local
3270 terminals. This value is only allowed for type 2 terminals.
2simple message optimisation + logical compression. Replacement of repeated characters by Repeat-
to-Address orders, and VIRTEL only sends to the terminal those characters which have changed
compared with the contents of the 3270 buer. The management of the MDT bits allows a further
optimization for inbound data, i.e. in the terminal to host direction. This level of compression
allows a gain of 40% to 60 %. This value is mandatory for type 1 and type 3 terminals.
3message optimisation + logical compression + learning of screen types. (VIRTEL/PC only) All mes-
sages destined for these terminals are subject to special processing. VIRTEL determines gradually
from their frequency of use which the most commonly used screen images and automatically cre-
ates a “screen type” referenced by number and stored at the host. When a message is to be sent
to a PC type terminal, VIRTEL performs a lookup to determine whether the message to be sent
can be associated with a “screen type”. If it can, then it sends a datastream representing the
dierence between the screen type and the nal desired result. The PC automatically learns the
“screen types” which it must use.
4.1. Introduction 105
Virtel Connectivity Guide, Release 4.58
This level of compression allows a reduction of approximately 80% of the message volume. It can for
example be used for PC’s connected at 1200 or 2400 Bps, thereby allowing response times approaching
those of a 9600 Bps synchronous line.
Note: This value can only be used for VIRTEL/PC connections. It is however possible to assign this
value to type 2 color terminals in order to facilitate the learning of “screen types”.
Possible calls Determines which calls can be made on this terminal. Depending on the associated line,
certain values are meaningless. For example, the value 2 (outgoing calls) is not appropriate for a
denition associated with an HTTP line since outgoing calls are impossible on this type of line.
In addition to being used to authorize incoming, outgoing, or both incoming and outgoing calls, this
parameter also has an eect during VIRTEL startup. Any terminal which has “Possible calls” set to
0 will not be activated at VIRTEL startup. Also note the“Possible calls” eld in the denition of the
associated line.
Write stats to Indicates the recording of statistics for the terminal entry.
Blank No statistics.
1Recording in VIRSTAT (classic format).
2Recording in VIRLOG.
4Recording in VIRSTAT (alternate format for X25).
5Recording in VIRSTAT (web format, alphanumeric).
6Recording in VIRSTAT (web format, with binary elds for the PRTSTATW program).
More than one value may be specied. For example:
12 Recording in both VIRSTAT (classic format) and VIRLOG.
24 Recording in both VIRLOG and VIRSTAT (alternate format).
124 Recording in VIRSTAT (classic and alternate formats) and VIRLOG.
VIRSTAT classic format recording is intended for use with Minitel calls on terminals associated with
NPSI lines (Gate or Fast Connect). VIRSTAT alternate format recording may be requested for termi-
nals associated with any X25 line (GATE, FASTC, XOT). Either of the two VIRSTAT web formats
may be requested for terminals associated with HTTP lines.VIRLOG recording may be requested for
terminals associated with X25 lines (GATE, FASTC, XOT) and HTTP lines. For terminals associated
with all other line types (including /GATE, /PCNE, and /FASTC) the statistics eld should be left
blank. Refer to the “Audit and Performance” chapter of the VIRTEL Messages and Operations Guide
for details of the VIRSTAT and VIRLOG record formats.
Repeat Up to 4 decimal digits indicating the number of desired repetitions of this terminal denition. See
“Repeated xed entries” for more details and examples. A repeat count of blank, zero, or 1 indicates
denition of a single terminal.
106 Chapter 4. Terminals
CHAPTER
FIVE
ENTRY POINTS
5.1 Introduction
Entry points dene the session context for a terminal or for certain types of lines. A terminal connecting to
VIRTEL must connect via an entry point. This section describes the functions associated with entry point
management, as well as the correlation with other elements of VIRTEL system administration, for example,
line and terminal management.
An entry point is a named entity that groups certain information designed to authorise, personalise and
protect access to the host site. Entry points dene the type of emulation required, the type of security
control, which sign-on screen must be sent to the user at log on time, what type of Multi-session menu must
be used and what applications are to be made available to the user.
5.1.1 Entry Point Management Sub-Application
The Entry Point Management sub-application is accessed by pressing [PF3] in the Conguration Menu, or
[PF13] in the Sub-Application Menu, or from the Multi-Session Menu via a transaction referencing module
VIR0044. This subapplication allows management of the parameters associated with each entry point.
5.1.2 Security
When security is active, access to entry point management from the Conguration Menu or the Sub-
Application Menu is controlled by the resource $$GLOG$$. When accessed by a transaction, the rules
governing the management of transaction security apply. Security management is described in chapter 4 of
the VIRTEL Technical Documentation.
5.1.3 Selecting an Entry Point
The entry point used in the connection from a terminal may be specied in various ways:
3270 Terminals
The entry point to be used for a connection from a 3270 terminal can be specied: - In the DATA parameter
of a logon sequence. For example: LOGON APPLID(VIRTEL) DATA(PE-0001) - In the VIRTEL terminal
denition (see “Parameters Of The Terminal”). - If no entry point is specied, the default entry point is the
rst value of the DEFENTR parameter in the VIRTCT. If this value does not exist, the terminal receives a
signon screen compatible with the original Multi-Session VIRTEL (before version 3.0).
107
Virtel Connectivity Guide, Release 4.58
Asynchronous terminals on X25 non-GATE lines
A Minitel connecting to VIRTEL in LLC5 mode uses a VIRTEL terminal not associated with any line (see
“Support of X25 non GATE terminals”, page 71). The entry point used for this type of connection can
be specied: - In the X25 call packet. The entry point is specied in the CUD (Call User Data) eld of
the call packet. The entry point name is in ASCII character format starting at the 5th byte of the CUD
eld, following the 4-byte protocol identier. - In the VIRTEL terminal denition (see “Parameters Of The
Terminal”, page 109). - If no entry point is specied, the default entry point is the second value of the
DEFENTR parameter in the VIRTCT. If this value does not exist, the terminal is rejected.
Incoming calls on X25 lines - GATE, FastC, XOT
The entry point to be used for an X25 connection (GATE, FastConnect, XOT) can be specied: - By the
rules of the line. If one of the rules associated with the line matches the characteristics of the call, the entry
point chosen by the rule takes precedence over that specied in the call packet. - In the X25 call packet.
The entry point is specied in the CUD (Call User Data) eld of the call packet. The entry point name is
in ASCII character format starting at the 5th byte of the CUD eld, following the 4-byte protocol identier.
- A default entry point can be specied in the line denition (see “Line Parameters”, page 11). - If no entry
point is specied, the default entry point is the second value of the DEFENTR parameter in the VIRTCT.
If this value does not exist, the call is rejected.
Incoming calls on HTTP or SMTP lines
For an incoming call on this type of line, the entry point is chosen: - By the rules of the line, if a rule
exists which matches the characteristics of the request. - Otherwise the default entry point specied in the
denition of the HTTP or SMTP line will be used.
Outgoing calls from an X25 application via a reverse X25 line - /GATE, /FASTC, or /PCNE
For an outgoing call from an application connected to VIRTEL via this type of line, the entry point is chosen
according to the following procedure. Note that incoming calls (network to application) on this type of line
are processed by the rules attached to the incoming line (X25 GATE, FASTC, XOT) and not by the rules
attached to the reverse X25 line. - The entry point dened in the terminal associated with the reverse X25
line, if specied. This value takes precedence over all other values. - The entry point chosen by the rules
of the reverse X25 line, if a rule matches the characteristics of the outgoing call from the application. -
The entry point specied in the Call User Data of the call packet sent by the application, if present. - The
default entry point dened in the reverse X25 line, if specied. - If no entry point was specied by any of the
preceding steps, the default is the second value of the DEFENTR parameter in the VIRTCT. If this value
does not exist, the call is rejected.
5.1.4 Summary Display
The entry point management application manages the entry points and their associated transactions. The
rst screen displayed shows a summary of existing entry points in alphanumeric order. A complete description
of each eld is presented in the following section.
108 Chapter 5. Entry Points
Virtel Connectivity Guide, Release 4.58
Entry Point Summary Display
Field Contents
Name: The name of the entry point.
Description: Description of the entry point.
Transaction: Prex of the names of the transactions associated with this entry point (maximum
6 characters).
Modifying an entry point denition: - To modify the denition of an entry point, enter the required
information in the eld then press [PF1]. Several denitions may be modied simultaneously. If the eld
you wish to modify does not appear on the summary screen, position the cursor on the entry and press
[PF12] to display the denition detail screen. Modications do not take eect until you press [PF1]. Certain
modications, for instance a modication to an entry point used by a line, require a restart of VIRTEL.
Deleting an entry point denition: - To delete a denition, position the cursor on the name of the
entry to be deleted and press [PF2]. The line associated with the entry to be deleted will appear highlighted
with the message CONFIRM DELETE. Press [PF2] again to conrm deletion. The message DELETE OK
conrms successful completion of the operation. Repeat the procedure for each entry to be deleted.
Adding an entry point denition: - To add a new denition, press [PF12] at the summary screen, either
with the cursor on an existing denition to copy certain of its attributes, or on an empty line to create a
new denition.
5.1.5 Transaction Display
To access the list of transactions associated with an entry point, position the cursor on the desired entry
point and press [PF4]. The transaction management menu will then appear.
5.1. Introduction 109
Virtel Connectivity Guide, Release 4.58
5.1.6 Detail Display
To display the details of an entry point, position the cursor on the desired entry point in the summary screen
and press [PF12].
Entry point detail display
5.1.7 Parameters
Name Represents the name of the entry point as specied in a logon sequence, or in the “Entry point” eld
of a terminal, line, or rule denition.
Description Describes the entry point.
Transactions Indicates the prex (0 to 6 charaters) of the transactions associated with this entry point.
Last page This eld, which is used only for HTTP connections, indicates the name of the HTML page
which will be displayed after the connection with the host application terminates. If blank, then the
default page (whose name is equal to the entry point name) will be displayed.
Note: For Minitel entry points, the “Last page” eld is not displayed, and the “Videotex key” eld
is displayed instead.
Videotex key This eld, which is used only for Minitel connections, indicates the key word used to direct
the request to the Minitel tree structure.
Note: If routing is not necessary, for example for STI or JOUTEL, the keyword $NONE$ may be
used.
Transparency Indicates the type(s) of external server(s) where translation from ASCII to EBCDIC must
not used.
110 Chapter 5. Entry Points
Virtel Connectivity Guide, Release 4.58
Time Out User inactivity timeout period (in minutes). If the user (or calling terminal) sends no messages
during this period,the “Do if timeout” procedure is invoked. This timeout takes eect only for terminals
using this entry point via HTTP, VIRTELPC, or X25 connections. It has no eect for 3270 connections.
The default is 720 minutes. A value of 0 implies no timeout.
Do if timeout Action to be taken if the value specied in the “Time Out” eld is exceeded.
0Break the session.
1Sound an alarm, the break the session if user takes no action.
2Generate an inaudible alarm to avoid X25 PAD timeout.
Note: While the terminal is connected to an external server application, session outage can also
occur if the timeouts specied in the external server denition are exceeded.
Emulation Indicates the type of emulation if the terminal using the entry point is not a 3270.
BORNE For Minitels without accentuated character support.
EBCDIC For asynchronous connections without ASCII / EBCDIC translation.
EMAIL For SMTP connections.
HTML For HTTP connections.
HOST4WEB or H4W For HTTP connections. Same as HTML, except that it also al-
lows HOST4WEB commands to be embedded in 3270 screens (for details, refer to the
“Programming Interfaces” section in the VIRTEL Web Access Guide).
MINITEL For Minitel connections in 40 or 80 column mode.
PC For connections via VIRTEL/PC.
VT For VT100 or VT200 type connections.
X25 For connections via Reverse-X25 or APPC2 lines.
$NONE$ For simple terminals in LUTYPE0 mode with ASCII translation. Even or odd
parity, if required, can be specied at the line level.
$NONE$-E Same as $NONE$ but without ASCII translation.
Signon program Indicates the name of the program used to control user sign-on with the active security
tool. If this eld is not completed, no sign-on control is performed. Allowable values for this eld are
listed in section 1.4.4 117.
Menu program Indicates the name of the program which presents the list of transactions which the user
is allowed to access. Permissible values are listed in section 1.4.5.
Identication scenario For emulation type MINITEL: Indicates the name of the program responsible for
physical identication of Minitels connecting to VIRTEL. For all other emulation types: Indicates the
name of the presentation module containing the identication scenario for this entry point.
Scenarios are described under the heading “Presentation modules” in the VIRTEL Web Access Guide.
Type 3 compression Indicates whether this entry point allows the use of level 3 compression. For more
information on this subject, refer to “Parameters Of The Terminal”. An ‘X’ in this eld activates
support for level 3 compression.
Mandatory identication Indicates whether connections made via VIRTEL/PC must present a physical
identication of the connecting PC. Refer to the chapter VIRTEL PC/VT100 for more information on
this subject. An ‘X’ in this eld activates the PC identication process.
5.1. Introduction 111
Virtel Connectivity Guide, Release 4.58
3270 swap key Indicates the function key which allows the user to return from a transaction to the Multi-
Session Menu. Permissible values are PF1 to PF24, PA1, PA2, PA3. If this eld is blank, the swap
key is specied by the SWAP parameter in the VIRTCT.
Extended colors An ‘E’ in this eld indicates support for 3270 extended attributes and colors. An ‘X’
indicates support for 3270 extended attributes and colors together with support for DBCS (Double
Byte Character Set).
5.1.8 Signon Programs
The Signon Program eld of the entry point indicates the name of the program used to control user sign-on.
The following signon programs are supplied with VIRTEL:
VIR0020A Standard program for sign-on processing by entry of USER/PASSWORD sequence via sign-on
screen.
VIR0020B Program used to process a logon sequence containing USER and PASSWORD. The logon
sequence must conform to the following format: LOGON APPLID(ACBVIRTEL) DATA(EP USER
PASSWORD) or EP (where EP is the entry point name).
VIR0020C Program identical to VIR0020B, but without any validity check on the password.
VIR0020H Sign-on program with WINDOWS user interface for HTTP mode.
VIR0020M Standard sign-on program for 40-column Minitel.
VIR0020L Standard sign-on program for 40-column Minitel by entry of USER and PASSWORD. The
sign-on screen is produced with the help of a Videotex overlay whose name is the same as the entry
point used. The source of this screen is in the member MAPSIGN. After changing the source, the
resultant phase or load module can be placed into a separate LOADLIB concatenated to DFHRPL.
VIR0020P Program similar to VIR0020L which allows access to public transactions (those dened with
security = 0), if sign-on is rejected by the security system.
5.1.9 Menu Programs
The Menu Program eld of the entry point indicates the name of the program which presents the list of
transactions which the user is allowed to access. The following program names can be specied:
VIR0021A Standard menu program for VIRTEL Multi-Session and HTTP.
VIR0021B Program for connecting to a single transaction. This program only manages transactions dened
in startup mode 1. The terminal is directly connected to the rst transaction dened in startup mode
1.
VIR0021C Program for connecting in Flip-Flop mode to authorized transactions. This program only
manages transactions dened in startup mode 1. The user is directly connected to the rst transaction
dened in startup mode 1. When the user exits this application, the user is automatically connected
to the next one and so on. When the last transaction in the list is reached, the user is reconnected to
the rst one. The use of a transaction referencing the LOGOFF subapplication allows the user to exit
from VIRTEL.
VIR0021D Program reserved for STI.
VIR0021E Program for connecting incoming X25 calls destined for an AntiPCNE line. This program
emulates the function of a VTAM logon interpret table. It reads the rst message and selects the
transaction whose external name matches the rst 8 characters of the message. If there is no matching
transaction then message VIR2151E is issued and the call is cleared.
112 Chapter 5. Entry Points
Virtel Connectivity Guide, Release 4.58
VIR0021F Program for connecting incoming X25 calls destined for an AntiPCNE line. This program
emulates the function of a VTAM logon interpret table. It reads the rst message sent by the partner
(known as the pre-connexion message) and selects the transaction whose “Logon message” eld matches
the start of the pre-connextion message. The “Logon message” eld can contain an EBCDIC character
string enclosed in apostrophes (case sensitive), or a hexadecimal string in the format X’hh…hh’. An
empty string (two apostrophes) matches any message. The pre-connexion message is passed on to the
application. If there is no transaction whose “Logon message” matches the pre-connexion message,
then console message VIR2161E is issued and the call is cleared.
VIR0021G Program for connecting incoming X25 calls destined for an AntiPCNE line. This program is
similar to VIR0021F except that (a) the pre-connexion message is not passed on to the transaction,
and (b) if the pre-connexion message does not match any transaction, the program continues to read
incoming messages until a match is found. The entry point may contain additional transactions whose
external name is USSMSGnn. These transactions do not participate in the matching of pre-connexion
messages, but instead are used to generate responses to the terminal during the preconnexion phase.
If a transaction with external name USSMSG10 is present, the contents of its “Logon message” eld
are sent to the terminal upon receipt of the call packet. If a pre-connexion message arrives from
the terminal which does not match any transaction, then the program looks for a transaction whose
external name is USSMSG01 and sends the contents of its “Logon message” eld to the terminal; if
there is no transaction named USSMSG01 then message VIR2172E is issued and the call is cleared. If
a transaction with external name USSMSG00 is present, the contents of its “Logon message” eld are
sent to the terminal immediately before the call is connected to the target application.
VIR0021J Program for connecting to the rst available transaction in a list. This program is similar to
VIR0021B, but instead of connecting to the rst transaction, it connects to the rst transaction whose
application is active. This allows VIRTEL to automatically select a backup application if the primary
application is down.
VIR0021M Standard menu program for 40-column Minitel. Identical to VIR0021A, this program is not a
Multi-Session program.
VIR0021O Program for connecting to a single transaction. Identical to VIR0021B, except that it does not
disconnect the terminal when the application nishes.
5.1. Introduction 113
Virtel Connectivity Guide, Release 4.58
114 Chapter 5. Entry Points
CHAPTER
SIX
TRANSACTIONS
6.1 Introduction
A transaction is a named entity that allows access to an “application” at the host site. The term “appli-
cation” may be either a VTAM application, a VIRTEL sub-application, an external server, or an HTML
directory. Each transaction is known to the user by its external name, and denes the rules of connection
/ disconnection of the referenced application. When a security tool is used, for example VIRTEL security,
only the transactions dened as resources appearing in the proles of a user are accessible by that user. Each
entry point has a list of associated transactions. The entry point management sub-application allows the
administrator to manage the entry point and its associated transactions.
6.1.1 Summary Display
Press [PF4] at the entry point detail screen to display the list of associated transactions:
Transaction Summary Display
Field Contents
115
Virtel Connectivity Guide, Release 4.58
Internal name Indicates the internal name of the transaction as it is known to the system. If a security
tool is used, this name must be dened as a resource. Only those users with the resource in one of
their proles can access this transaction.
Note: Note that on the Multi-Session Menu, these transactions appear by alphanumeric order of their
internal name.
External name Indicates the name of the transaction as it is known to the end user. This name appears
in eld [10] of the Multi-Session Menu, as shown in the chapter describing Multi-Session. This is also
the name by which the transaction is referenced in an HTTP request.
Description Caption associated with the transaction. This caption appears on the Multi-Session Menu.
Application Indicates the name of the application accessed via the transaction. This application can be a
VTAM application, a VIRTEL sub-application, an external server, or a directory of HTML pages.
Navigation
The list can be positioned in the following ways:
Search Type the name, or the partial name, of the desired entity in the rst line of the rst column and
press [Enter].
[PF6] Return to the rst page of the list.
[PF7] Display the previous page of the list.
[PF8] Display the next page of the list.
Modifying a transaction denition - To modify the details of a transaction, type the required changes
in the appropriate elds and press [PF1]. You can change more than one denition at a time. To modify a
eld not shown on the summary screen, position the cursor on the transaction and press [PF12] to display
the transaction detail screen. Important note: Changes do not take eect until you press [PF1]. After
updating a transaction denition, you must also update the entry point(s) concerned by pressing [PF3] twice
(to return to the list of entry points) then [PF1] to register the change(s) to the entry point.
Deleting a transaction denition - To delete a denition, position the cursor on the name of the trans-
action to be deleted and press [PF2]. The line associated with the transaction to be deleted will appear
highlighted with the message CONFIRM DELETE. Press [PF2] again to conrm deletion. The message
DELETE OK conrms successful completion of the operation. Repeat the procedure for each transaction to
be deleted.
Adding a transaction denition - To add a new denition, press [PF12] at the summary screen, either
with the cursor on an existing denition to copy certain of its attributes, or on an empty line to create a
new denition. Complete all required elds and press [ENTER]. The message CREATE OK indicates that
the operation completed successfully
6.1.2 Detail Display
To access the detailed transaction denition, position the cursor on the desired transaction and press [PF12].
The transaction detail denition screen will then be displayed.
116 Chapter 6. Transactions
Virtel Connectivity Guide, Release 4.58
Transaction Detail Screen - non-HTML transaction
Transaction Denition Screen - HTML transaction
6.1.3 Parameters
Internal name The name of the transaction as it is known to the system. The rst “n” characters of
this name are the prex by which the transaction is linked to one or more entry points. Transaction
security is based on this internal name. It should be noted that the transactions are placed on the
Multi-Session Menu in alphanumeric order of the internal name.
6.1. Introduction 117
Virtel Connectivity Guide, Release 4.58
External name The name of the transaction as it is presented to the user in the selection screen. This is
also the name by which the transaction is referenced in an HTTP request (see “VIRTEL URL formats”
in the VIRTEL Web Access Guide).
Description The descriptive label associated with the transaction as it is presented to the user in the
selection screen.
Application The name of the application associated with the transaction. This application can be a VTAM
application, a VIRTEL sub-application, an external server, a directory containing HTML pages, or the
name of a VIRTEL line. When the “Application Type” is 3 (external server), the following values have
special meaning:
&L the server name is the same as the terminal name
&R the server name is the same as the relay name
&1 the server name is the same as the “parameter” eld of the rule which matched the
incoming call
=(for incoming calls via a VIRPESIT line only) the server name is the same as the desti-
nation partner name specied in the PESIT le transfer header.
For application type 3 or 4, you can press [PF12] to display the detailed denition of the external
server or HTML directory.
When the “Application Type” is 5, this eld contains the internal or external name of a VIRTEL line.
Application type 5 is used by the SEND$ TO and SEND$ VARIABLE-TO instructions (see “VIRTEL
Scenarios” in the VIRTEL Web Access Guide)
PassTicket Indicates whether VIRTEL should generate les PassTickets for this application. Possible values
are:
0(default value) indicates that VIRTEL should not generate PassTickets for this application.
1species that VIRTEL should generate a PassTicket, using the specied RACF application
name, if the user has signed on to VIRTEL. The PASSTCK=YES parameter must also
be specied in the VIRTCT.
2species that VIRTEL should generate a PassTicket, even if the user has not signed on to
VIRTEL. The PASSTCK=YES parameter must also be specied in the VIRTCT.
Note: Note: The value 2 implies that the user has supplied the userid in some other way, for exam-
ple by means of a scenario containing the COPY$ VARIABLE-TO-SYSTEM,FIELD=(NAME-OF,USER)
instruction (see VIRTEL Web Access Guide)
Name The name of the application as known to RACF for generation of PassTickets. This may be dierent
from the VTAM application name.
Application Type Denes the type of application described in the “Application” eld. Permissible values
for this eld are:
1for a VTAM application
2for a VIRTEL sub-application
3for an external server
4for a directory containing HTML pages
5for a reference to a VIRTEL line
118 Chapter 6. Transactions
Virtel Connectivity Guide, Release 4.58
Pseudo Terminals Species the prex of the name of the VIRTEL terminal which will be used to connect
to the application. The value $LINE$ in the “Pseudo Terminals” eld indicates that this transaction
is reserved for HTTP connections using non-predened terminals (see “HTTP connections with non-
predened LU names”).
Logmode The name of the new LOGMODE that MUST be used to connect to the application. This
overrides any LOGMODE parameter specied in the URL or in an identication scenario.
How started Represents the desired startup mode for the transaction. Permissible values are as follows:
1The transaction is integrated in the primary list. If authorised after security checking, it
will appear in the primary Multi-Session menu. User intervention will be required to
access this application, unless menu programs VIR0021B or VIR0021C are used.
2The transaction is integrated in the secondary list. If authorised after security checking, it
will appear in the Multi-Session sub-menu. User intervention will be required to access
this application.
3The transaction is integrated in the primary list with automatic startup when the terminal
connects to VIRTEL. If several transactions dened with automatic startup appear in
the primary list, only the last one in the hierarchy is activated at connection time.
Do not confuse automatic startup in transparent mode (menu program VIR0021B + transaction startup
mode 1) with automatic startup oering the possibility to return to a selection menu screen (menu
program other than VIR0021B or VIR0021C + transaction startup mode 3).
Note: Note than startup mode 4 which was present in VIRTEL prior to version 4.0 has been replaced by
value 0 in the “Security” eld.
Security The type of security applied to the transaction.
0Public transaction. A public transaction is always available whatever security tool is used.
1Secure transaction (Basic security). A secure transaction is only available to a user if au-
thorized by the active security tool. For HTTP access, the user is prompted, if necessary,
for a userid and password.
Note: if passphrase is not active then passwords will be truncated to the rst 8
characters. Passphrase support is activated by the PASSPHRASE option of the SECUR
keyword in the TCT. See the Virtel Installation Guide for further details.
2Secure transaction (NTLM security). For HTTP access only, security type 2 allows VIR-
TEL to obtain the Windows userid of the user, without prompting the user to signon
again. The active security tool must recognize the userid and grant access to the trans-
action. This type of security should only be used on a LAN or on an encrypted session.
3Secure transaction (Certicate security). A transaction with type 3 security must be
accessed via HTTPS (secure session), and the client browser must present a certicate
recognized by the active security tool (RACF). The userid associated with the certicate
must be granted permission by the security tool to access the transaction. Type 3 security
is only possible when running z/OS V1R7 or later, using a secure connection provided
by AT-TLS
4Secure transaction (HTML security). Used with HTTP access, security type 4 allows
VIRTEL to obtain the userid and password of the user from elds supplied in the HTML
page. The elds must be declared by means of the DECLARE-FIELD-AS tag in the page
6.1. Introduction 119
Virtel Connectivity Guide, Release 4.58
template. For more details, refer to the section “Creating HTML and XML template
pages: Signon and password management” in the VIRTEL Web Access Guide.
Translation(s) Type(s) of translation supported for MINITEL connections. Specify one or more of the
following values:
0Same type of translation required in the sub-server node denition.
13270 messages are processed in 80 column format but are only displayed as 40 columns
unless otherwise specied (for example, if $%80 is present in the data stream).
23270 messages are processed in and displayed in 80 column format unless otherwise spec-
ied (for example, if $%40 is present in the data stream). Modes 1 and 2 are mutually
exclusive.
33270 messages are processed in 40 column format. This mode is used only for certain IMS
applications.
4Automatic detection of translation mode. This mode supports applications which pro-
duce both 3270 messages and videotex messages. VIRTEL adapts the display format
automatically according to the type of message being processed. For example suppose a
transaction dened with translation modes 2 and 4 is accessed from a sub-server node.
Messages from this application will be automatically displayed as if they were already
in videotex format (mode 4) or displayed directly in 80 column format for other cases
(mode 2). This translation mode is compulsory for SRTV applications. For transactions
attached to an entry point type HTML, HOST4WEB, or H4W the eld “Translation(s)”
is replaced by the eld “H4W commands”
H4W commands For HTTP connections, this eld indicates under what conditions HOST4WEB com-
mands should be processed. Specify one of the following values:
0Never process HOST4WEB commands.
1Always process HOST4WEB commands.
2Process HOST4WEB commands only if the rst eld of the message begins with the
characters “2VIRTEL”.
4Process HOST4WEB commands if either (a) the entry point species emulation type
HOST4WEB or H4W, or (b) the entry point species HTML and the rst eld of
the message begins with the characters “2VIRTEL”. These values are meaningful only
when the entry point species emulation type HTML, HOST4WEB, or H4W. For further
details, refer to the “Programming Interfaces” section in the VIRTEL Web Access Guide.
Logon message Application type 1: Character string sent to the application as “Logon data” at connection
time. This string may also contain certain script variables and orders as described below. Application
type 3: For transactions associated with an entry point which species menu program VIR0021F or
VIR0021G (see “Menu Programs”) this eld is used to identify incoming calls. For type 4 (HTML
directory denition) transactions, the eld “Logon message” is replaced by the eld “Check URL
Prex”
Check URL Prex Application type 4: If the pathname of a URL matches the character string specied
in this eld, then the pathname corresponds to the VIRTEL directory whose name is specied in the
“Application” eld. See “How the path name corresponds to a VIRTEL directory” in the “VIRTEL
URL formats” section of the VIRTEL Web Access Guide.
TIOA at logon Application types 1-3: Script to be run at application connection time. Scripts are de-
scribed under the heading “Connection – Disconnection Scripts”. Application type 4: For type 4
(HTML directory denition) transactions having the same name as an entry point, the “TIOA at lo-
gon” eld contains the default URL for the entry point. Refer to the “VIRTEL URL formats” section
of the VIRTEL Web Access Guide for further details.
120 Chapter 6. Transactions
Virtel Connectivity Guide, Release 4.58
TIOA at logo Application types 1-3: Script to be run before disconnecting from the application.
Initial Scenario
Final Scenario
Input Scenario
Output Scenario
For HTML transactions, each of these elds may contain the name of an HTML presentation module. For
each eld which is non-blank, VIRTEL will call the corresponding scenario (INITIAL, FINAL, INPUT, or
OUTPUT) in the named presentation module. An OUTPUT scenario may also be referenced by a VIRTEL
Multi-Session transaction.
Note: Scenarios are described under the heading “Presentation modules” in the VIRTEL User Guide.
Warning: After adding, deleting or updating a transaction, it is essential to update the entry points
used by this transaction by pressing [PF1] at the entry point summary screen.
6.1. Introduction 121
Virtel Connectivity Guide, Release 4.58
122 Chapter 6. Transactions
CHAPTER
SEVEN
CONNECTION / DISCONNECTION SCRIPTS
When connecting to an application, it may be useful, if desired, to automatically execute certain operations to
direct the user to a dened point within the application. The most commonly used operations are application
signon procedures. Similarly, when the user logs o from an application, it can be useful to run various
commands to release application resources. These operations are called “connection and disconnection
scripts”. Scripts are entered in the elds “TIOA at logon” and “TIOA at logo” of a transaction, or in the
“TIOA at start up” eld of an external server, with the help of the language described below. A script can
send data and 3270 attention keys to the application, send data to the terminal, and wait for specic data
from the application.
7.1 Script Programming Language
A connection / disconnection script consists of a sequence of “clauses”. A clause consists of some data (which
may contain embedded variables and orders) followed by a command. All commands, variables, and orders
begin with the ‘&’ character.
7.1.1 Transmission and lter commands
The command acts upon the data which precedes it. The commands are as follows:-
Desired operation Com-
mand
Transmit the preceding data to the application &/A
Transmit the preceding data to the terminal &/T
Ignore and discard the current application message &/I
Wait until the application sends a message containing the character string specied in the
preceding data
&/W
Same as &/W except that messages are still sent to the terminal while being ltered &/F
Kill the script (connection / disconnection) &/K
Note: Any blanks immediately following a &/ command are ignored.
For compatibility with versions of VIRTEL prior to 4.31, the / (slash) in the above commands may also be
coded as the EBCDIC character whose hexadecimal value is X’4F’. In the US, Canada, and UK codepages,
X’4F’ is represented by a vertical bar. In some European countries, X’4F’ appears as an exclamation point.
123
Virtel Connectivity Guide, Release 4.58
7.1.2 System variables
System variables are information known only to VIRTEL at the time of accessing an application. These
variables are in the format &n where “n” represents the desired variable. Available information Corresponding
variable:-
Available information Corressponding variable
Transaction name &T
VTAM terminal name &L
Transaction external name &X
Transaction description &D
Application name &A
Call User Data (12 bytes) &C
Relay name &R
User name &U
User password &P
Rerouting parameters &1, &82, &83,…, &8F
URL parameter &=paramn=
VIRTEL variable &=varname=
Note 1 System variables may also be coded in the Logon Message eld.
Note 2 The system variable &=name= is used to obtain the value of either a URL parameter or of a
VIRTEL variable created by a scenario (described in the VIRTEL Web Access Guide). If both a
URL parameter and a VIRTEL variable exist with the same name then the VIRTEL variable takes
precedence.
7.1.3 Orders
Orders may be embedded in the clause data. Orders are used to set the 3270 (or Minitel) attention key to
be sent by the following &/A command, to embed hexadecimal or special values in the data, or to cause the
script to wait for the rst message from the application, or to process a scenario.
124 Chapter 7. Connection / Disconnection Scripts
Virtel Connectivity Guide, Release 4.58
Information to be sent Corresponding order
Set the AID and cursor ad-
dress for a 3270 read opera-
tion. See note 1
&*xxrrcc where xx is: F1-F9=PF1-PF9, 7A-7C=PF10-PF12,
C1-C9=PF13-PF21, 4A-4C=PF22-24, 7D=Enter; rrcc is the cursor ad-
dress in 3270 buer address format
Set the AID for a 3270 short
read operation (note 2)
&#yy or &*yy where yy is: 6C=PA1, 6E=PA2, 6B=PA3, 6D=Clear,
FD=Attn
Minitel keys in external server &*0Dxx40 where xx is: F1=Guide, F2=Repet, F3=Somm, F4=Annul,
F7=Retour, F8=Suite, F9=Copier, 7B=EndPage, 7C=Corr, 7D=Envoi,
6D=Conn/Fin
Data in hexadecimal (note 4) &’hhhhhhhhhhh’
Ampersand character (note 4) &&
Wait for rst message (note 3) &W
Write preceding character
string to console and discard
&/M
Start of repeating script for
service transaction (note 5)
&(
End of repeating script for ser-
vice transaction (note 5)
&)
Execute scenario (note 6) &/S
Use tab key to skip to next
available input eld (note 7)
&>
Note 1 If a function key occurs in the middle of a script, the transmission sequence for the function key
must be &*xxrrcc&/A. Where the function key is at the end of the script, there is no need to add
&/A. If &/A or end of script occurs with no AID key specied, the default is &*7D4040 (Enter with
cursor at row 1 col 1).
Note 2 Never use &/A to send PA keys or Clear to the application.
Note 3 The &W order is processed only if it appears at the start of the script; otherwise it is ignored.
Note 4 Orders &’hh…hh’ and && may also be coded in the Logon Message eld.
Note 5 &( and &) enclose a section of the script which will be repeated. When the script reaches the &)
order, the transaction is converted into a “service transaction” and remains active waiting for similar
requests from other users (see “Service transactions” in the VIRTEL Web Access Guide).
Note 6 The &/S order executes a scenario. If coded in the connexion script (“TIOA at logon”), it exe-
cutes the INITIAL scenario of the presentation module named in the “Initial Scenario” eld of the
transaction. If coded in the disconnexion script (“TIOA at logo”), it executes the FINAL scenario
of the presentation module named in the “Final Scenario” eld of the transaction (see “Presentation
modules” in the VIRTEL Web Access Guide). Any data preceding the &/S order is ignored. Any
blanks immediately following the &/S order are ignored.
Note 7 The &> order does not transmit anything and must be completed with a transmission order. This
order can be concatenated as many times as necessary before transmission. Exemple : &>&> can be
used to simulate two tab key usage.
7.1.4 Method of operation
If present, a script is rst called when the initial connection is made to the application. VIRTEL examines
the start of the script to see if it begins with the order &W (wait for rst message from application). If so,
then no further action is taken at this time, and script processing continues after the rst message is received
from the application. Otherwise, the rst clause of the script is actioned according to its command code, as
follows:
7.1. Script Programming Language 125
Virtel Connectivity Guide, Release 4.58
• &/W, &/F, &/I : no further action is taken at this time, the clause will be reprocessed when the rst
message arrives from the application
• &/T, &/A : the data preceding the command is transmitted to the terminal or application
• &/K : the connection is scheduled for termination
Subsequently, VIRTEL processes one clause of the script each time a message arrives from the application.
Each clause is actioned according to its command code, as follows:
• &/W : VIRTEL tests whether the data preceding the &/W command appears in the message. If the
data is not found, then the message is discarded, and the &/W clause is processed again when the next
message arrives from the application. If the data is found, then the message is discarded and the next
clause in the script is immediately processed.
• &/F : VIRTEL tests whether the data preceding the &/F command appears in the message. If the
data is not found, then the message is sent to the terminal, and the &/F clause is processed again when
the next message arrives from the application. If the data is found, then the message is discarded and
the next clause in the script is immediatelyprocessed.
• &/I : the application message is discarded.
• &/T, &/A : the data preceding the command is transmitted to the terminal or application.
• &/K : VIRTEL will send the message and immediately disconnect the communication, without waiting
for the response (asynchronous mode used with certain servers).
Data sent to the application by means of the &/A command must be constructed in the format expected
by the application. In the case of a 3270 application, the message is in the form of a 3270 data stream.
VIRTEL adds a standard 3-byte 3270 prex (consisting of AID character and cursor SBA) which defaults
to default is 7D4040 but may be overridden by a &* or &£ order embedded in the preceding script data. In
the case of a Minitel application, VIRTEL adds the appropriate sux (0Dxx) as indicated by an &* order
embedded in the preceding script data (see table of script orders below).
Data sent to the terminal by means of the &/T command must be constructed in the same format as the
application would generate. In the case of a 3270 application, the message must be in the form of a 3270
data stream prexed by a 3270 command code and WCC. VIRTEL will translate the message to the format
required by the terminal (for example, HTML or Minitel) as appropriate.
7.2 Script Examples
Note: In these examples, script commands are introduced by the preferred sequence &/ (ampersand slash).
For compatibility with existing scripts created before version 4.31 of VIRTEL, the slash may optionally be
replaced by the EBCDIC character whose hexadecimal value is X’4F’.
7.2.1 Connect to CICS (no sign-on) with automatic start of a transaction
In the simplest case, the CICS transaction code is entered in the eld “TIOA at logon”. The script below
simply sends the ABC1 transaction code to CICS at connection time:
Internal name ===> W2H-10 To associate with an entry point name
External name ===> Cics Name displayed on user menu
Description ===> Logon to CICS
Application ===> ACBCICS Application to be called
Application type ===> 1 1=VTAM 2=VIRTEL 3=SERV 4=PAGE 5=LINE
126 Chapter 7. Connection / Disconnection Scripts
Virtel Connectivity Guide, Release 4.58
Pseudo-terminals ===> DEVT Prefix of name of partner terminals
Security ===> 0 0=none 1=basic 2=NTLM 3=TLS 4=HTML
Logon message ===>
TIOA at logon ===> ABC1
Connection script to start a CICS transaction
This example works only if the CICS TYPETERM denition species LOGONMSG(NO). If CICS is con-
gured to send an initial message to the terminal at logon, by means of the LOGONMSG(YES) parameter,
then a bracket error would occur when the above script is executed. To avoid this, the transaction code
must be prexed by &W to wait for the initial message to be delivered, as shown in the next example.
7.2.2 Connect to CICS and start transaction CESN with transmission of credentials
The variables &U and &P can be used to pass the current VIRTEL userid and password to the CICS signon
transaction:-
Internal name ===> W2H-11 To associate with an entry point name
External name ===> Cics2 Name displayed on user menu
Description ===> Logon to CICS
Application ===> ACBCICS2 Application to be called
Application type ===> 1 1=VTAM 2=VIRTEL 3=SERV 4=PAGE 5=LINE
Security ===> 1 0=none 1=basic 2=NTLM 3=TLS 4=HTML
Logon message ===>
TIOA at logon ===> &WCESN&/ASignon&/F&*7D4EC9&'114BE9'&U&'114CF9'&P&/A
Connection script with automatic signon to CICS
This script waits for the initial message from CICS, then enters the transaction code CESN. It waits for the
“Signon” prompt to be displayed, then enters the userid and password in two separate elds and sends the
completed screen to the host. Security=1 is specied to ensure that the user is signed on to VIRTEL. The
SBA orders 11xxxx identify the position of the userid and password elds in the CESN signon panel and
may vary as a function of the site.
7.2.3 Connect to CICS VSE with ICCF sign-on and start transaction CEMT
The following script illustrates the use of a PF key:
Internal name ===> W2H-12 To associate with an entry point name
External name ===> ICCF Name displayed on user menu
Description ===> Logon to CICS VSE
Application ===> DBDCCICS Application to be called
Application type ===> 1 1=VTAM 2=VIRTEL 3=SERV 4=PAGE 5=LINE
Security ===> 1 0=none 1=basic 2=NTLM 3=TLS 4=HTML
Logon message ===>
TIOA at logon ===> REMOTE&/W&'11E35C'&U&'11E560'&P&/AEscape&/W&*F64040&/ACEMT&/A
Connection script with automatic signon to ICCF
This script waits for the ICCF signon screen (recognized by the word ‘REMOTE’), then enters the userid
and password in two separate elds and sends the completed screen to the host. It waits for the ICCF main
menu (recognized by the word “Escape”) and presses F6. It then enters the transaction code CEMT. The
SBA orders 11xxxx identify the position of the userid and password elds in the ICCF signon panel and may
vary as a function of the site.
7.2. Script Examples 127
Virtel Connectivity Guide, Release 4.58
7.2.4 Connect to TSO with USER and PASSWORD and await start of ISPF
This is an example of an HTTP transaction which uses the “Logon Message” eld to pass the userid to TSO,
followed by a script to complete the TSO/ISPF logon process:
Internal name ===> W2H-13 To associate with an entry point name
External name ===> Tso Name displayed on user menu
Description ===> Logon to Tso
Application ===> TSO Application to be called
Application type ===> 1 1=VTAM 2=VIRTEL 3=SERV 4=PAGE 5=LINE
Security ===> 1 0=none 1=basic 2=NTLM 3=TLS 4=HTML
Logon message ===> &U
TIOA at logon ===> TSO/E LOGON&/W&'11C9C3'&P&/A***&/W&/A
Connection script with automatic logon to TSO/ISPF
The script waits for the TSO/E LOGON panel for the specied userid, then enters the password into the
appropriate eld. It waits for the *** prompt to appear, and presses enter. Security=1 is specied to ensure
that the user is already signed on to VIRTEL. The SBA order 11C9C3 identies the password eld (at row
8 col 20) in the TSO/E LOGON panel and may vary as a function of the site.
7.2.5 Connect to CICS and navigate a user applicaction
Internal name ===> W2H-14 To associate with an entry point name
External name ===> Cics4 Name displayed on user menu
Description ===> Logon to CICS
Application ===> ACBCICS2 Application to be called
Application type ===> 1 1=VTAM 2=VIRTEL 3=SERV 4=PAGE 5=LINE
Security ===> 1 0=none 1=basic 2=NTLM 3=TLS 4=HTML
Logon message ===>
TIOA at logon ===> &'F5C21140401D4013'&/TWELCOME&/W&*7D40C1
TIOA at logoff ===> &#6BCESF LOGOFF&/A
Connection script with message to terminal
This script sends an initial 3270 message to the terminal to format the screen and position the cursor.
The data in this initial message consists of a 3270 Write-Erase command (F5), a Write Control Character
(C2), a Set Buer Address order (114040), a Start Field order (1D40) and an Insert Cursor order (13).
Having sent this message, the script waits for the CICS application to send a message containing the string
“WELCOME”, then it sends the “Enter” key to the CICS application. When the terminal user disconnects,
the logo script sends the “Clear” key to CICS followed by CESF LOGOFF.
7.2.6 Service Transaction
This example shows a script which connects to CICS and repeatedly issues an enquiry transaction whose
parameters are supplied in the URL of an HTTP request:
Internal name ===> W2H-15 To associate with an entry point name
External name ===> Cics5 Name displayed on user menu
Description ===> CICS Service Transaction
Application ===> ACBCICS2 Application to be called
Application type ===> 1 1=VTAM 2=VIRTEL 3=SERV 4=PAGE 5=LINE
Security ===> 1 0=none 1=basic 2=NTLM 3=TLS 4=HTML
Logon message ===>
TIOA at logon ===> Signon to CICS&/W&*F34BE9&/A&(TRA1&=MYPARAM=&/A&)
128 Chapter 7. Connection / Disconnection Scripts
Virtel Connectivity Guide, Release 4.58
Connection script for service transaction
The rst part of this script signs on to CICS using the default CICS userid. This part of the script is
executed once only when the VIRTEL transaction is called for the rst time. The remainder of the script,
bracketed by the &( and &) orders, is executed repeatedly. Because the script has a repeating part, this
transaction is known as a “Service Transaction”. Each time an HTTP request arrives in the form http://
ipaddr:port/pagename+cics5?myparam=xyz123 it is dispatched to the service transaction, if one is available,
and the script executes the CICS transaction TRA1xyz123 where xyz123 is the value of the URL parameter
“myparam=” specied in the HTTP request. The result of this CICS transaction is returned to the requester
using pagename as a page template. The request is then terminated, but the session between VIRTEL and
CICS remains connected waiting for the next request.
7.2. Script Examples 129
Virtel Connectivity Guide, Release 4.58
130 Chapter 7. Connection / Disconnection Scripts
CHAPTER
EIGHT
EXTERNAL SERVERS
8.1 Introduction
The external server management sub-application allows the administrator to maintain the call parameters
relating to the various servers available for outgoing calls. External server denitions allow users at 3270
terminals to access Videotex servers via an X25 network. Additionally, starting with VIRTEL version 4.14,
the concept of an external server is extended to handle the routing of incoming and outgoing calls to and
from X25 GATE/PCNE applications such as CFT and Inter.PEL. Starting with VIRTEL version 4.42, the
external server may also be used to dene the parameters for outbound calls to a PESIT/IP le transfer
server via a VIRPESIT line.
8.1.1 External Server Management Sub-Application
The external server management sub-application is accessed by pressing [PF7] in the Conguration Menu, or
[PF11] in the Sub-Application Menu, or from the Multi-Session Menu via a transaction referencing module
VIR0031. This subapplication allows management of the parameters associated with each external server.
8.1.2 Security
When security is active, access to external server management from the Conguration Menu or the Sub-
Application Menu is controlled by the resource $$SERV$$. When accessed by a transaction, the rules
governing the management of transaction security apply. Security management is described in chapter 4 of
the VIRTEL Technical Documentation.
8.1.3 Summary Display
The rst screen displayed by the external server management sub-application shows a summary of existing
denitions in alphanumeric order:
131
Virtel Connectivity Guide, Release 4.58
External Server Summary Display
Navigation
In browse, alter, or delete mode, it is possible to scroll the list of external servers under the control of
VIRTEL.
Search Type the name (or partial name) of the required entity on the rst line under the heading “Service”,
then press [Enter].
[PF6] Return to the rst page of the list.
[PF7] Display the previous page.
[PF8] Display the next page.
Modifying an external server denition - Type the desired modications into the appropriate elds then
press [PF1]. Multiple denitions can be modied at the same time. The message UPDATE OK indicates
that the modications have been accepted. If the modication aects a eld not displayed on the summary
screen, rst position the cursor on the denition concerned, then press [PF12] to access the denition detail
screen.
Deleting an external server denition - To delete a denition, position the cursor on the name of
the service to be deleted and press [PF2]. The line associated with the service to be deleted will appear
highlighted with the message CONFIRM DELETE. Press [PF2] again to conrm deletion. The message
DELETE OK conrms successful completion of the operation. Repeat the procedure for each external
server to be deleted.
Adding an external server denition - To add a new denition, press [PF12] at the summary screen,
either with the cursor on an existing denition to copy its attributes, or on an empty line to create a new
denition.
132 Chapter 8. External Servers
Virtel Connectivity Guide, Release 4.58
8.1.4 Detail Display
To access the detailed denition of an external server, position the cursor on the desired service in the
summary screen and press [PF12]. The external server detail denition screen will then be displayed. To
return to the conguration menu, press [PF3] or [Clear].
External Server Detail display
8.1.5 Parameters
Name Contains the name of the service as displayed to the user in the “Call External Server” screen. This
name may also be referenced in the “Application” eld of a type 3 transaction.
Description Description of the service as displayed to the user in the “Call External Server” screen.
Number For outbound calls via an X25 line:
The X25 call number required to access the service.
If the service is invoked by an X25 incoming call, the called number can be dened as “=”. In this
case, the called number for the outgoing call will be copied from the incoming call packet. In the case
of an external server which processes outgoing calls originating from an application linked to VIRTEL
via an AntiGATE line (CFT, Pelican), the value “=” indicates that the called number will be supplied
by the application. In the case of an external server which processes outgoing calls originating from a
VIRKIX application, the “Number” eld must be blank, which indicates to VIRTEL that the called
number and the caller number, as well as the data, facilities, and CUD0 (if applicable), will all be
supplied by application. However, if the “Caller” eld of the external server is non-blank, then this
value will override the caller number supplied by the application. For this type of external server, the
entry point must contain a transaction whose external name is “Mirror” as the rst transaction.
For outbound calls via a VIRPESIT line:
The IP address of the partner in the form nnn.nnn.nnn.nnn
8.1. Introduction 133
Virtel Connectivity Guide, Release 4.58
Data For outbound calls via an X25 line:
User data. The contents of this eld will be converted to ASCII and placed in the outgoing call packet
immediately following the contents of the CUD0 eld. If the service is invoked by an X25 incoming
call, the data can be dened as “=”. In this case, the Call User Data for the outgoing call (Data and
CUD0 elds) will be copied from the incoming call packet. In the case of an external server invoked
by an HTTP request, for example:
GET /PUBLIC/WEB3270.htm+videotex+SERVICE1
the value “=” indicates that the parameter (SERVICE1 in this example) will be placed
,→in ASCII in the outgoing call packet immediately following the CUD0 field.
For outbound calls via a VIRPESIT line:
The TCP port number of the partner.
Line number Species the internal name of the line on which the outgoing call will be made. The line type
may be either X25 (GATE, FASTC, XOT, AntiGATE, AntiPCNE, AntiFC) or TCP with protocol
VIRPESIT. “*” indicates that the rst available line will be used.
Note: For users of VIRTEL prior to version 4.20:
External server denitions which were created using a version of VIRTEL prior to 4.20 refer
to the line using a single character name. When processing these denitions, VIRTEL selects
the rst line whose internal name begins with the character specied, and VIRTEL displays the
complete name of the selected line in this eld on the external server denition detail screen.
When the external server denition is updated for the rst time under VIRTEL 4.20 or later, the
single character reference is replaced in the external server denition by the complete line name.
Prior to VIRTEL version 4.20, if the “Line number” eld of the external server was blank, the
line selected for the outgoing call was the rst line whose internal name began with the gure
1. From VIRTEL version 4.20 onwards, it will be necessary to update any such external server
denitions, by specifying explicitly the full internal name of the required line.
Backup line The internal name of the backup line which will be used for the outgoing call if the primary line
is not available. Following an error on the primary line, VIRTEL uses the backup line for all subsequent
calls. Similarly, following an error on the backup line, VIRTEL switches back to the primary line for
all subsequent calls. From version 4.24 onwards, if both the primary and backup lines are available
and operational, both will be used for outgoing calls. For each line, VIRTEL maintains a counter
of outgoing calls which have been made but which have not yet received a response. Before making
each call, VIRTEL compares the counters of each of the two lines, and selects the line with the lowest
number of calls awaiting response. This procedure has the eect of balancing the load between the two
lines, and bypasses possible blockages caused by router errors. The rules for specifying the backup line
are the same as for the primary line.
Caller Optional caller number to be placed in the outgoing call packet. If the service is invoked by an X25
incoming call, the caller number can be dened as “*” or “=”. In this case, the caller number for the
outgoing call will be copied from the incoming call packet.
Emulation Type of emulation required. Possible values are:
0no emulation (Called by FA25 API)
1VIRTELPC emulation
2Minitel 40 column emulation, reverse X25, or VIRPESIT
3Minitel 80 column emulation
134 Chapter 8. External Servers
Virtel Connectivity Guide, Release 4.58
4VT100 emulation
53174 switched node
6VT200 emulation
7Minitel emulation with LECAM via VIRNT
8BULL emulation
Character set Type of characters expected by the external server.
1ASCII 7 bits
2ASCII 8 bits
3EBCDIC
Server time out Timeout period (in seconds) for the server. VIRTEL will disconnect the call if the server
sends no messages during this period. 0 indicates that there is no timeout.
User time out Timeout period (in minutes) for the caller. VIRTEL will disconnect the call if the caller
sends no messages during this period. If 0 is specied, the value of the TIMEOUT parameter in the
VIRTCT is used instead.
Cut o warning Type of message sent to the user before disconnection occurs due to user time out.
Possible values are:
0User receives no warning of disconnection
1User is warned by an audible ‘bip’ 30 seconds before disconnection
2User is warned by a message 30 seconds before disconnection or if the server does not respond
Price level The tari for this service. Possible values are:
0Cost is not calculated for this service
n(n is a value from 1 to Z), the cost of the call is calculated and presented to the user at the end of
the connection. The values of n are dened in VIRTEL exit 7 (see VIRTEL Installation Guide).
Secret 1 indicates that this service will not appear in the list of servers shown to the user in the “Call
External Server” screen. This value is typically used in external server denitions which are intended
to be called only by a type 3 transaction.
Facilities Optional facilities (in hexadecimal) to be placed in the X25 call packet.
If the service is invoked by an X25 incoming call, the facilities can be dened as “=”. In this case, the
facilities for the outgoing call will be copied from the incoming call packet.
If neither packet size (42) nor window size (43) appears in the facilities specied here or copied from
the incoming call packet, then VIRTEL will generate packet size and window size facilities elds in the
outgoing call packet according to the values specied in the outbound line denition.
CUD0 (hex) Protocol indicator (2 to 8 hexadecimal characters) to be placed in the outgoing call packet
before the user data. If this eld is blank, the default value is 01000000 (indicating PAD protocol).If
the value of the “Data” eld is “=” then the “Data” and “CUD0” will be copied from the incoming
call packet.
TIOA at start up Contains a connection script to be run immediately after connection to the server. For
more information, see “Connection – Disconnection Scripts”.
8.1. Introduction 135
Virtel Connectivity Guide, Release 4.58
136 Chapter 8. External Servers
CHAPTER
NINE
CONNECTION MODES
There are various methods of connecting terminals to VIRTEL. This chapter includes the WELCOME and
RELAY modes of connection
9.1 WELCOME mode
Exclusively for 3270 terminals, WELCOME mode allows 3270 terminals to connect to VIRTEL without being
predenied. There are two conditions which must be fullled: - The ACCUEIL parameter in the VIRTCT
must be set to YES, - The connecting terminal must not match any existing xed terminal denition or
terminal pool denition.
In this mode, terminals not dened in VIRTEL can connect, but they cannot benet from compression or
full Multi- Session functionality. The rst screen displayed depends on the characteristics of the entry point
used. If no entry point is used, each terminal connecting in WELCOME mode will see the VIRTEL sign-on
screen, or the Multi-Session Menu, or the Conguration Menu depending on the options specied in the
VIRTCT for the SECUR and MULTI parameters.
If the Multi-Session Menu is accessible from a terminal connected in WELCOME mode, it is regarded simply
as a selection screen. Thus, when an application is selected, VIRTEL connects the terminal directly to this
application and relinquishes control of the terminal. In this case, VIRTEL functions somewhat like a dynamic
USSTAB.
9.2 RELAY mode
3270 terminals can be connected in RELAY mode if a suitable denition exists in the system. The relays
are dened to VTAM by means of APPL statements. Each terminal connected in this way can benet from
VIRTEL compression and/or Multi-Session functionality. Whether a sign-on screen or a Multi-Session Menu
is displayed depends on the characteristics associated with the entry point used. When no entry point is
used, the rules described in the previous paragraph apply.
9.3 Terminal Connection Types
The denition of a terminal / relay pair can be accomplished in various ways: by means of a xed entry; by
inclusion in a physical pool (which may be dynamic or non-dynamic); or by means of a reserved entry (logical
pool). A xed entry is a denition which can only be used by one specic terminal. A physical pool is a
generic denition which can be shared by several dierent terminals. A logical pool is a reserved denition
which is used not for connecting a terminal to VIRTEL, but for connection to a VTAM application. This
137
Virtel Connectivity Guide, Release 4.58
denition allows the same physical terminal, for example a Minitel, to be presented to applications with
dierent relays depending on the context. Each type of denition can be explicit or repeated.
. index:: pair: Connection Modes; Explicit Fixed Terminal entries
9.3.1 Explicit xed entries
Each terminal in the group is explicitly named within VIRTEL. This mode of denition is useful when a
group of relays must be attached to a line via a common terminal name prex, but the relay LU names do
not follow a numeric pattern. The following example shows a group of terminals and corresponding relay
LU names associated with a line via prex PCN1:
LIST of TERMINALS ---------------------------------- Applid: SPVIRH1 18:15:52
Terminal Repeated Relay Entry Type I/O Pool 2nd Relay
PCN1TM01 0001 PARIS 3 1
PCN1TM02 0001 ROMA 3 1
PCN1TM03 0001 BERLIN 3 1
PCN1TM04 0001 BRUSSEL 3 1
PCN1TM05 0001 DENHAAG 3 1
PCN1TM06 0001 KOBNHAVN 3 1
PCN1TM07 0001 LONDON 3 1
PCN1TM08 0001 DUBLIN 3 1
P1=Update P2=Delete P3=Return P6=1st Page
P7=Page-1P8=Page+1P12=Details
Explicit xed terminals
Repeated xed entries
Only the rst terminal in the list is dened. The repeat count indicates the number of terminals which
VIRTEL will create. The numeric portion of the terminal name, relay name, and 2nd relay name (if
supplied) are incremented for each occurrence of the terminal.
Note: The repetition increment takes eect from the rightmost numeric character and continues until the
next nonnumeric character to the left. The increment is decimal and not hexadecimal.
Examples
In the examples shown below: - Terminal TERM0001, relay RELAY001, repetition 0016 causes the creation
of 16 terminals TERM0001 to TERM0016 with relays RELAY001 to RELAY016. - Terminal G001T001,
relay RELAY200, repetition 0020 causes the creation of 20 terminals G001T001 to G001T020 with relays
RELAY200 to RELAY219. - Terminal TER00LUA, relay REL00CVA, 2nd relay FIX00CVA, repetition 0100
causes the creation of 100 terminals TER00LUA to TER99LUA with relays REL00CVA to REL99CVA and
2nd relays FIC00CVA to FIC99CVA. - The remaining examples show invalid repetitions caused by improper
denitions. In each case the size of the numeric portion of one or more of the names is insucient to allow
the generation of a unique name for each occurrence in the repeat range.
LIST of TERMINALS ---------------------------------- Applid: SPVIRH1 18:13:49
Terminal Repeated Relay Entry Type I/O Pool 2nd Relay
TERM0001 0016 RELAY001 PC 2 3
G001T001 0020 RELAY200 3 3
TER00LUA 0100 REL00CVA 3 3 FIC00CVA
TERX0LUB 0015 REL00CVB 3 3 FIC00CVB
TER00LUC 0015 RELX0CVC 3 3 FIC00CVC
138 Chapter 9. Connection Modes
Virtel Connectivity Guide, Release 4.58
TER00LUD 0015 REL00CVD 3 3 FICX0CVD
TER90LUE 0015 REL00CVE 3 3
P1=Update P2=Delete P3=Return P6=1st Page
P7=Page-1P8=Page+1P12=Details
Repeated xed terminals
9.3.2 Physical Terminal Pools
Physical pools allow 3270 terminals to connect to VIRTEL and to be assigned a relay LU, without the need
to create an individual deninition for each connecting terminal. A relay LU is assigned from the physical
pool at the time the terminal connects to VIRTEL. There are two types of physical pool, dynamic and
non-dynamic, as described later.
Whether or not a pool is dynamic, the denition of a physical pool is indicated by the presence of a “?”
character in the rst position of the terminal name. The next three characters denote the characteristics of
the pool. The last four characters are free-format and serve to distinguish one denition from another.
A physical pool thus has a name in the format ?xxxyyyy.
The concept of a physical pool only applies to 3270 terminals. Other types of terminal cannot be dened by
means of a physical pool.
Although a physical pool allows connection of a large number of terminals, it is sometimes necessary to restrict
the connection to certain types of terminals This selection is done with the three characters represented by
“x” in the name of the physical pool denition.
1st character Tests the terminal type.
*No restriction on terminal type
SSNA terminal
NNon SNA terminal
2nd character Tests the terminal model
*No restriction on model
2 to 5 Restricted to specied model
3rd character Tests colour support
*No restriction on colour support
CColour terminal
NMonochrome terminal
Examples:
• ?S**YZABVIRTEL tests only if the terminal is SNA.
• ?S3CYZABVIRTEL tests if the terminal is SNA model 3 colour.
9.3.3 Dynamic Terminal Pools
In a dynamic physical pool, the associated relay is dened by a combination of alphanumeric characters and
“=” signs. Each “=” sign will be dynamically replaced by the value of the corresponding character in the
name of the connecting terminal.
9.3. Terminal Connection Types 139
Virtel Connectivity Guide, Release 4.58
For example, for a denition specifying VIR===== as the relay name, each terminal connecting to VIRTEL
will be allocated a relay whose rst three characters are VIR and whose last ve characters are the last ve
characters of the terminal LU name. VIRTEL must be able to open a VTAM application LU for each possible
relay dened in the pool. The use of the VTAM generic character “?” allows all possible relay names to be
dened to VTAM by a single APPL statement, as shown in the following example:
VIR????? APPL AUTH=(ACQ,PASS)
A single denition may be sucient to connect all 3270 terminals in the network.
9.3.4 Non-Dynamic Terminal Pools
In a non-dynamic physical pool, the associated relay is dened by a combination of alphanumeric characters
without “=” signs. A given terminal may be assigned a dierent relay on each connection according to
availability. Each relay in the pool must be dened to VTAM by means of an APPL statement.
It is advisable to dene as many entries as there are terminals to be connected.
9.3.5 Terminal Pool Denition Examples
Physical Pool
In the examples shown below, ?***0000 is a dynamic physical pool which allows connection of an unlimited
number of terminals. ?S5CTM01 is a non-dynamic physical pool which allows connection of up to 8 terminals
(of type 3270-5 SNA Colour) which will be assigned relay names VIR5LU01 to VIR5LU08.
LIST of TERMINALS ---------------------------------- Applid: SPVIRH1 18:13:49
Terminal Repeated Relay Entry Type I/O Pool 2nd Relay
?***0000 VIR===== PC 2 3
?S5CTM01 0008 VIR5LU01 PC5 2 3
P1=Update P2=Delete P3=Return P6=1st Page
P7=Page-1 P8=Page+1 P12=Details
Physical pools of terminals
Logical pool
A logical pool is a group of relays which are not permanently assigned to any terminal. Instead, the relays
in the group are available for allocation by terminals as and when required. The logical pool is dened as a
group of terminals (the denitions can be explicit or repeated) whose “*Pool name” eld contains a name
prexed preceded by the character “*”. The terminal name is not signicant, except to distinguish it from
other terminal denitions. Terminals which use the pool specify the pool name (with the “*” prex) in their
relay name eld. The dierence between a logical pool and a physical pool is that a relay in a physical pool
is assigned when the requesting terminal connects, whereas a relay in a logical pool is assigned at the time
the requesting terminal needs the relay to connect to a VTAM application.
In the example shown below, W2HTP000 is a logical pool whose pool name is *W2HPOOL. The logical pool
contains 16 relay LU’s named RHDVT000 to RHDVT015, with associated printer LU’s named RHDIM000
to RHDIM015. The relays in 7. Terminals 117 the *W2HPOOL logical pool are available for use by
terminals CLVTA000-015, DEVTA000-015, and HTVTA000-015. Appropriate VTAM APPL statements
must be provided for RHDVT??? And RHDIM???.
140 Chapter 9. Connection Modes
Virtel Connectivity Guide, Release 4.58
LIST of TERMINALS ---------------------------------- Applid: SPVIRD1 18:02:53
Terminal Repeated Relay Entry Type I/O Pool 2nd Relay
?***0000 RVTAM=== PC 2
CLLOC000 0010 3 3
CLVTA000 0016 *W2HPOOL 3 3
DELOC000 0010 3 3
DEVTA000 0016 *W2HPOOL 3 3
HTLOC000 0016 3 3
HTVTA000 0016 *W2HPOOL 3 3
SMLOC000 0016 SMTP 3 3
W2HIM000 0016 RHDIM000 S 1
W2HTP000 0016 RHDVT000 3 3 *W2HPOOL RHDIM000
P1=Update P2=Delete P3=Return P6=1st Page
P7=Page-1 P8=Page+1 P12=Details
Denition of a logical pool of terminals
Terminals using a logical pool are dened with a “Relay” eld referencing the logical pool rather than a
VTAM APPL statement.
9.3.6 Terminal Pool Selection
When a 3270 terminal is dened to a physical pool, the selection of a pool is managed automatically by
VIRTEL at connection time. It starts from the end of the list of dened terminals. When the characteristics
of the terminal match those of the entry being processed, the terminal assumes an application relay.
Rules for opening relay ACBs
For explicit or repeated xed entry denitions, the relay ACBs are opened at VIRTEL startup time. For
terminals dened in a physical pool, the relay ACBs are opened at terminal connection time. For terminals
which reference a logical pool, the relay ACB is opened only when accessing an application.
Use of a terminal logical pool
When a single terminal must be presented under a dierent name according to the applications it logs on to
across the same line, a logical pool must be used.
Note: Logical pools are not usable on X25 Fast-Connect lines managed by NPSI. The following examples
reference type 3 (Fast-Connect) terminals, used for example on an XOT line.
As a concrete example, suppose that Minitels use an X25 line with 50 logical channels to logon to 3 distinct
applications under dierent names according to sub-address or a specic user data value. The rst two
applications are accessible via the same entry point ENTRYP01, the third via entry point ENTRYP02.
Applications APPLI01, APPLI02, APPLI03 must be accessed via relays with prexes AP01R, BP02R and
CP03R respectively. The rst application only allows 5 simultaneous logons, the second has no limit, and
the third allows 2 simultaneous logons. The set of VIRTEL denitions to resolve this problem is as follows.
Terminal Denitions
9.3. Terminal Connection Types 141
Virtel Connectivity Guide, Release 4.58
The denition of the physical terminals and their association with the 3 sub-groups of logical terminals
belonging to the same pool is:
DEFINITION OF X25 TERMINALS
Terminal Repeat Relay Entry Type Compression 2nd Relay
XOTF0001 0050 *POOL001 Libre 3 2 Vide
DEFINITION OF 3GROUPS OF RESERVED TERMINALS
Terminal Repeat Relay Entry Type Compression 2nd Relay
ARESA001 0005 AP01R001 Libre 3 2 Libre
BRESA001 0050 BP02R001 Libre 3 2 Libre
CRESA001 0002 CP03R001 Libre 3 2 Libre
Note: These 3 terminal groups contain the value *POOL001 under the heading “*Pool name” in their
denition. When virtual printers are associated with a logical pool, they may be dened as xed explicit or
repeated entries, but they must not be placed in a logical pool.
Entry point denitions
The two entry points are assigned transactions TRPE01 and TRPE02 respectively.
DEFINITION OF ENTRY POINTS
Name Description Transactions
ENTRYP01 EP for APPLI01 and APPLI02 TRPE01
ENTRYP02 EP for APPLI03 TRPE02
Transaction denitions and terminal selection
Transactions TRPE0101, TRPE0102 and TRPE0203 are dened as illustrated below.
DEFINITION OF THE FIRST TRANSCACTION FOR ENTRYP01
Nom interne ===> TRPE0101 Pour l'associer a un point d'entrée
Nom externe ===> APPLI-01 Nom affiche dans le menu utilisateur
Description ===> Application 01 avec terminaux ARESA
Application ===> APPLI01 Application gérant la transaction
Alias ===> Nom suite a CLSDST PASS
Type d'application ===> 1 1=VTAM 2=VIRTEL 3=SERVEUR 4=PAGES
Terminaux ===> ARESA Préfixe des terminaux associés
DEFINITION OF THE SECOND TRANSCACTION FOR ENTRYP01
Nom interne ===> TRPE0102 Pour l'associer a un point d'entrée
Nom externe ===> APPLI-02 Nom affiche dans le menu utilisateur
Description ===> Application 02 avec terminaux BRESA
Application ===> APPLI02 Application gérant la transaction
Alias ===> Nom suite a CLSDST PASS
Type d'application ===> 1 1=VTAM 2=VIRTEL 3=SERVEUR 4=PAGES
Terminaux ===> BRESA Préfixe des terminaux associés
DEFINITION OF THE FIRST TRANSCACTION FOR ENTRYP02
Nom interne ===> TRPE0201 Pour l'associer a un point d'entrée
Nom externe ===> APPLI-03 Nom affiche dans le menu utilisateur
142 Chapter 9. Connection Modes
Virtel Connectivity Guide, Release 4.58
Description ===> Application 03 avec terminaux CRESA
Application ===> APPLI03 Application gérant la transaction
Alias ===> Nom suite a CLSDST PASS
Type d'application ===> 1 1=VTAM 2=VIRTEL 3=SERVEUR 4=PAGES
Terminaux ===> CRESA Préfixe des terminaux associés
9.4 Terminal Connection Examples
This section presents a number of examples covering the denitions relating to terminals and details the
parameters required on the VIRTEL and VTAM sides. The list is not exhaustive.
9.4.1 3270 terminal in WELCOME mode
This mode allows any terminal to logon to VIRTEL. The ACCUEIL parameter in the VIRTCT must be set
to YES. There must be no denition which allows an application relay to be assigned to the terminal.
9.4.2 3270 terminal in RELAY mode
A VTAM APPL statement must be dened for each terminal. If there is no such denition then message
VIR0005W is issued at VIRTEL startup time. Example denitions:
DEFINITION EXPLICITE
Terminal Répété Relais Entrée Type Compression 2eme Relais
TERM0001 0000 RELAY001 Libre 2Libre Vide
TERM0002 0000 RELAY003 Libre 2Libre Vide
TERM0003 0000 RELAY004 Libre 2Libre Vide
TERM0004 0000 RELAY005 Libre 2Libre Vide
DEFINITION REPETEE
Terminal Répété Relais Entrée Type Compression 2eme Relais
TERM0001 0004 RELAY001 Libre 2Libre Vide
DEFINITION DYNAMIQUE
Terminal Répété Relais Entrée Type Compression 2eme Relais
?***0001 0000 RELAY=== Libre 2 Libre Vide
DEFINITION EN POOL NON DYNAMIQUE
Terminal Répété Relais Entrée Type Compression 2eme Relais
?***0001 0000 RELAY001 Libre 2 Libre Vide
?***0002 0000 RELAY002 Libre 2 Libre Vide
?***0003 0000 RELAY003 Libre 2 Libre Vide
?***0004 0000 RELAY004 Libre 2 Libre Vide
9.4. Terminal Connection Examples 143
Virtel Connectivity Guide, Release 4.58
9.4.3 Asynchronous terminal on an X25 or XOT line
A VTAM APPL statement must be dened for each terminal. If there is no such denition then message
VIR0005W is issued at VIRTEL startup time. Example denitions:
EXPLICIT DEFINITION WITHOUT PSEUDO-PRINTER
Terminal Répété Relais Entrée Type Compression 2eme Relais
X25F0001 0000 RX25F001 Libre 3 2 Libre
X25F0002 0000 RX25F002 Libre 3 2 Libre
X25G0001 0000 RX25G001 Libre 1 2 Libre
X25G0002 0000 RX25G002 Libre 1 2 Libre
REPEATED DEFINITION WITHOUT PSEUDO-PRINTER
Terminal Répété Relais Entrée Type Compression 2eme Relais
X25F0001 0004 RX25F001 Libre 3 2 Libre
X25G0001 0004 RX25G001 Libre 3 2 Libre
EXPLICIT DEFINITION WITH PSEUDO-PRINTER
Terminal Répété Relais Entrée Type Compression 2eme Relais
FICTF001 0000 IMPRF001 Vide 2 0
FICTF002 0000 IMPRF002 Vide 2 0
FICTG001 0000 IMPRG001 Vide 2 0
FICTG002 0000 IMPRG002 Vide 2 0
X25F0001 0000 RX25F001 Libre 3 2 IMPRF001
X25F0002 0000 RX25F002 Libre 3 2 IMPRF002
X25G0001 0000 RX25G001 Libre 1 2 IMPRG001
X25G0002 0000 RX25G002 Libre 1 2 IMPRG002
DEFINITION REPETEE AVEC IMPRIMANTE FICTIVE
Terminal Répété Relais Entrée Type Compression 2eme Relais
FICTF001 0002 IMPRF001 Vide 2 0
FICTG001 0002 IMPRG001 Vide 2 0
X25F0001 0002 RX25F001 Libre 3 2 IMPRF001
X25G0001 0002 RX25G001 Libre 1 2 IMPRG001
The value entered in the “2nd Relay” eld of an X25 terminal corresponds to the value in the “Relay” eld
of the pseudo-printer denition. Pseudo-printer denitions are type 2 and do not correspond to any terminal
known to VTAM.
9.4.4 Logical terminals
It is possible to assign a physical terminal to a relay when a transaction connects the terminal to an appli-
cation, instead of when the terminal connects to VIRTEL. An example of such a denition is:
PHYSICAL TERMINAL DEFINITION
Terminal Repeat Relay Entry Type Compression 2nd Relay
144 Chapter 9. Connection Modes
Virtel Connectivity Guide, Release 4.58
TERM0001 0050 *POOL001 Free Free 2Empty
DEFINITION OF 3GROUPS OF RESERVED TERMINALS
Terminal Repeat Relay Entry Type Compression 2nd Relay
TRESA001 0005 RELAYA01 Free 2or 3 2 Free
TRESB001 0050 RELAYB01 Free 3or 3 2 Free
TRESC001 0002 RELAYC01 Free 3or 3 2 Free
The 3 groups of terminals contain the value *POOL001 under the heading “*Pool name” in their denition.
When virtual printers are associated with a logical pool, they must be dened as xed explicit or repeated
entries – they cannot be placed in a logical pool.
9.4. Terminal Connection Examples 145
Virtel Connectivity Guide, Release 4.58
146 Chapter 9. Connection Modes
CHAPTER
TEN
CONTROLLING LUNAMES
10.1 Introduction
In this section we look at how we can control LUNAME selection for inbound HTTP calls. When a user
connects to a 3270 application through VIRTEL Web Access, VIRTEL makes it appear to the application
as if the user is connecting from a virtual 3270 terminal. In VTAM terms a virtual 3270 terminal is called a
Logical Unit or LU, and each LU has a unique eight character name (LU name). VIRTEL has at its disposal
a pool of LUs known to VTAM, whose names are specied in the VIRTEL conguration le (the VIRARBO
le). Normally when a user connects to a 3270 application, VIRTEL chooses any available LU from the pool.
While most mainframe applications will accept a connection from any LU name, certain applications (par-
ticularly applications which run under IMS) are sensitive to the LU name because they assign permissions
to the user based upon the LU name of the user’s terminal. LU nailing allows VIRTEL to assign a particular
LU name to a user based one of the following:-
• By IP address
• By by cookie
• By by URL
10.2 LU Nailing By URL
The URL can contain information which can be used to force an LUNAME. This is done by by using either
the FORCELUNAME= keyword or by using the UserData in the URL.
Using UserData to select an LU name requires that a rule be associated with the line whereas this is not
required for the ForceLUNAME option. The rule is used to determine the action taken on processing the
UserData. Coding the desired LU name, or alternatively an LU name prex terminated by an asterisk, in
the “Parameter” eld of the Virtel Rule which selects the incoming HTTP request. Alternatively, if the value
$URL$ is entered in the “Parameter” eld of the Virtel rule, then the desired LU name will be taken from
the userdata supplied in the caller’s URL (see “VIRTEL URL formats: Dynamic pages” in the VIRTEL
Web Access Guide).
For example:-
http://192.168.170.33:41003/w2h/appmenu.htm+applist+myluname UserData example
or
http://n.n.n.n:41002/w2h/web2ajax.htm+IMS+ForceLUNAME=RLHVT500 ForceLUNAME example
147
Virtel Connectivity Guide, Release 4.58
10.2.1 UserData example using a work station name
In this example we use a batch job on the user’s PC to initiate a session with Virtel. The batch job obtains
the terminal name of the work station, opens a browser window and passes the work station name through to
Virtel. With a Virtel RULE we can test the name of the workstation and assign a particular relay LUNAME
from a Virtel terminal POOL.
Here is an example of a Virtel RULE.
RULE ID=ESH0000,
RULESET=E-HTTP,
STATUS=ACTIVE,
DESC='Rule for terminal EHPMA00',
ENTRY=EDSWHOST,
PARAM=EHPMA000,
NETMASK=255.255.255.255,
USERDATA=(EQUAL,HOLT-W)
The rule instructs Virtel to test the UserData eld passed in a URL and if it matches the string HOLT-
W than to assign an LU name prex of EHPMA00 and directs the terminal call to use an entry point of
EDSWHOST. A static rule would have to be built for each unique work station name.
Getting the PC workstation name to Virtel is through a batch job which res up the default browser and
passes the work station name as a user data parameter. Here is an example:-
title Test Propagation of Userdata Parameter
@echo on
color 1f
cls
SET P1=%COMPUTERNAME:~0,6%
start http://192.168.170.33:41003/w2h/appmenu.htm+applist+%P1% &goto:eof
:exit
The SET command takes the rst six characters of the work station name and passes it into the start
command. Following the Virtel transaction I wish to execute which in this case is an APPLIST menu list.
The start command will open a default browser window and connect to Virtel:-
148 Chapter 10. Controlling LUNAMEs
Virtel Connectivity Guide, Release 4.58
Passing User Data to Virtel
When a transaction is selected from the menu list the RULE will be invoked to allocate the correct LUNAME.
Selecting a LU name through a rule and work station id in the URL
10.2. LU Nailing By URL 149
Virtel Connectivity Guide, Release 4.58
The Virtel RULE has forced an LU name prexed EHPMA000 to be used from the VIRTEL terminal pool
associated with the Virtel line. In this case relay LUNAME EHPMA000 has been allocated.
10.2.2 UserData example using a LU Name
Instead of passing a work station name in the user data eld of the URL in this example we are passing an
LU name. Again with a Virtel RULE we can extract the user data parameter from the URL and use that
as the Virtel relay LUNAME name.
http://192.168.170.33:41003/w2h/appmenu.htm+applist+EHPMA00*
For this example the rule looks like:-
RULE ID=ESH0001,
RULESET=E-HTTP,
STATUS=ACTIVE,
DESC='Rule for terminal EHPMA00',
ENTRY=EDSWHOST,
PARAM=$URL$,
NETMASK=255.255.255.255
We use the special PARAM=$URL$ which indicates that the VTAM LU Name to be used is the user data
passed in the URL.
Using $URL$ to pass a LU name in the URL
150 Chapter 10. Controlling LUNAMEs
Virtel Connectivity Guide, Release 4.58
The user data in the URL, in this case EHPMA00*, will be added to each transaction in the APPLIST
menu and used as the Virtel relay LUNAME. When connecting to an application VIRTEL will use the LU
name dened in the URL. In this example we are using a generic LUNAME which supports a range from
EHPMA000 through to EHPMA009.
10.2.3 ForceLUNAME Example
In the preceding examples both required that a terminals and relays be predened. For some installations
this could be a maintenance headache and doesn’t scale up very well. It is possible for an HTTP client to
connect to VIRTEL with a parameter specifying an arbitrary VTAM LU name to be used as relay name for
host applications. For this to work, four conditions must be fullled:-
• the VTAM LU name should be specied in the connection URL. For example, if the desired LU name
is RLHVT500:
http://n.n.n.n:41002/w2h/web2ajax.htm+IMS+ForceLUNAME=RLHVT500
• the VIRTEL transaction must speciy $LINE$ in the “Pseudo-terminals” eld instead of a terminal
name prex.
• the HTTP line must specify a pool name
• a terminal pool of the same name should be dened; only the pool is needed, not the predened pseudo-
terminals that are normaly dened alongside a pool. The terminal and printer pseudo-terminals will
be automatically generated using the pool as a template together with the relay name specied in the
ForceLUNAME parameter of the URL.
The ForceLUNAME=luname parameter in the URL is valid only for transactions which specify TERMI-
NAL=$LINE$ when attached to a line which has an associated terminal pool.
In this example the transaction whose external name is IMS dened under entry point CLIWHOST. The
terminal prex in the transaction denition is $LINE$:
Transaction denition using non-predened LU names
10.2. LU Nailing By URL 151
Virtel Connectivity Guide, Release 4.58
The denition of line C-HTTP on port 41002 species *MYPOOL as the line pool name:
HTTP line denition using non-predened LU names
The denition of the terminal pool *MYPOOL contains mask characters in the “Relay” and “2nd relay”
elds. When a terminal is dynamically created, each “=” sign is substituted by the corresponding character
in the ForceLUNAME parameter of the URL:
Terminal pool denition using non-predened LU names
..note:
The name of the pool is only used to match the pool to its associated line.
152 Chapter 10. Controlling LUNAMEs
Virtel Connectivity Guide, Release 4.58
Using these denitions with URL parameter ForceLUNAME=RLHVT500 will dynamically generate two
pseudo- terminals: RLHVT500 for the terminal session, and RLHPR500 for the associated printer.
The TCT option RTERM= can be used to check that ForceLUNAME parameter. If RTERM=classname is
specied in the TCT than a RACHECK against the ForcedLUNAME will be executed to ensure that the
luname is allowed for a particular user.
Note: The presence of a ForceLUNAME=luname parameter in the URL implies $UseCookieSession$. If a
valid VirtelSession cookie is supplied, which corresponds to a currently active session, then the request will
be reconnected to that session. If no VirtelSession cookie is present, or if the cookie does not correspond to
any currently open session, then an LU name will be constructed by applying the value of the ForceLUNAME
parameter with the mask specied in the pool associated with the line. If the LU name constructed in the
preceding step is already in use then the request will be rejected with HTTP code 406. Otherwise a new
session will be opened using the constructed LU name.
10.2. LU Nailing By URL 153
Virtel Connectivity Guide, Release 4.58
10.3 LU Nailing by cookie
Virtel also can use cookies to select a relay LU name. Virtel uses a cookie as a part of the “Correspondence
Sub Application’. Within the cookie sent to Virtel is a security token. This token is used to identify a user
and their associated VTAM LU relay name. A Correspondent le is used to maintain the user details. The
cookie can be sent to the use as part of an Email from which the User selects a link to access Virtel or it can
be part of the ‘self-registration’ process. For further information see the How-To document Virtel – How to
Activate LU Nailing.
154 Chapter 10. Controlling LUNAMEs
Virtel Connectivity Guide, Release 4.58
10.4 LU Nailing by IP address
The Virtel Rules attached to the HTTP line allow the LU name to be selected according to the caller’s IP
address, by using the elds “IP Subnet” and “Mask” in the rule to match with an IP address or range of IP
addresses. The Virtel Rules associated with a user allow an LU name to be assigned according to a variety
of dierent criteria. For example such as a user’s e-mail address [Correspondent Management] which in this
case, the user is identied by a “Cookie” which the browser presents to VIRTEL with the HTTP request.
See “Virtel Rules”, for further information on Virtel Rules.
This technique uses a rule to associate an IP address with an LU Name. The rule is associated with a line. In
the example below we dene a rule on line W-HTTP which will force a terminal connecting with IP address
192.168.000.039 to use LU name RHTVT001. The LU name must be pre-dened in a Virtel terminal pool.
DETAIL of RULE from RULE SET: W-HTTP ------------- Applid: SPVIRBW 14:30:38
Name ===> WHT00110 Rule priority is per name
Status ===> ACTIVE 15 Feb 2010 14:30:35 SPTBOWL
Description ===> HTTP access from IP 192.168.0.39
Entry point ===> WEB2HOST Target Entry Point
Parameter ===> RHTVT001 &1value or LUNAME
Trace ===> 1=commands 2=data 3=partner
C : 0=IGNORE 1=IS 2=IS NOT 3=STARTS WITH 4=DOES NOT 5=ENDS WITH 6=DOES NOT
1IP Subnet ===> 192.168.000.039 Mask ===> 255.255.255.255
0Host ===>
0eMail ===>
0Calling DTE ===> Calling DTE address or proxy
0Called ===> Called DTE address
0CUD0 (Hex) ===> First 4bytes of CUD (X25 protocol)
0User Data ===>
0Days ===> M: T: W: T: F: S: S:
0Start time ===> H: M: S: End time ===> H: M: S:
P1=Update P3=Return Enter=Add
P4=Activate P5=Inactivate P12=Entry P.
Rule to map IP address 192.168.100.nnn to LU pool RHTVT1xx
Multiple terminals can be dened with a rule by using the * sux. In the following example a range of IP
address is mapped to a pool of LU names. Address range 192.168.100.0 through to 192.168.100.255 will be
assigned the next unused LU name in the range RHTVT1xx.
DETAIL of RULE from RULE SET: W-HTTP ------------- Applid: SPVIRBW 17:53:56
Name ===> WHT00140 Rule priority is per name
Status ===> ACTIVE 15 Feb 2010 17:53:49 SPTBOWL
Description ===> HTTP access from IP 192.168.100.nnn
Entry point ===> WEB2HOST Target Entry Point
Parameter ===> RHTVT1* &1value or LUNAME
Trace ===> 1=commands 2=data 3=partner
C : 0=IGNORE 1=IS 2=IS NOT 3=STARTS WITH 4=DOES NOT 5=ENDS WITH 6=DOES NOT
1IP Subnet ===> 192.168.100.000 Mask ===> 255.255.255.000
0Host ===>
0eMail ===>
0Calling DTE ===> Calling DTE address or proxy
0Called ===> Called DTE address
0CUD0 (Hex) ===> First 4bytes of CUD (X25 protocol)
0User Data ===>
0Days ===> M: T: W: T: F: S: S:
0Start time ===> H: M: S: End time ===> H: M: S:
P1=Update P3=Return Enter=Add P4=Activate P5=Inactivate P12=Entry P.
10.4. LU Nailing by IP address 155
Virtel Connectivity Guide, Release 4.58
Rule to map IP address 192.168.100.nnn to LU pool RHTVT1xx
The new rule is named WHT00140, the “IP Subnet” eld species the IP address 192.168.100.000, and the
“Mask” is set to 255.255.255.000 to indicate that only the rst three octets of the IP address are tested to
determine whether the rule matches the IP address of the client browser. The “parameter” eld species a
generic LU name RHTVT1* which signies that any LU whose name begins with RHTVT1 may be assigned
to clients whose IP address matches this rule.
156 Chapter 10. Controlling LUNAMEs
Virtel Connectivity Guide, Release 4.58
10.5 Comparison Table
Type RULE Required TERMINAL Denition
Reqd.
COOK-
IES
Terminal POOL
Reqd.
By UserData Yes. 1 per work
station
Yes. Individual or
group
No Yes
By $URL$ - LUNAME in
URL
Yes. 1 generic
Rule.
Yes. Individual or
group
No Yes
ForceLUNAME No No No Yes
By IP (Correspondent) Yes Yes Yes Yes
By IP Yes Yes No Yes
10.5. Comparison Table 157
Virtel Connectivity Guide, Release 4.58
158 Chapter 10. Controlling LUNAMEs
CHAPTER
ELEVEN
AT-TLS SECURE SESSION
11.1 Introduction
This section provides details on on to implement AT-TLS security. To provide secure HTTP (https) sessions
to client browsers, VIRTEL uses the Application Transparent Transport Layer Security (AT-TLS) feature
of z/OS Communication Server. AT-TLS is included with z/OS V1R7 and later releases.
AT-TLS allows socket applications to access encrypted sessions by invoking system SSL within the transport
layer of the TCP/IP stack. A Policy Agent task decides which connections are to use AT-TLS, and provides
system SSL conguration for those connections. Virtel continues to send and receive clear text over the
socket, but data sent over the network is encrypted and protected by system SSL. The supported protocols
are TLS, SSLv3, and SSLv2.
Warning: Higher CPU usgage will result in the TCP/IP address space if this feature is used without
the services of a hardware Crypto Card.
11.2 Installation
11.2.1 Install Policy Agent procedure
If you do not already have the Communications Server Policy Agent (PAGENT) active in your z/OS sys-
tem, copy the cataloged procedure EZAPAGSP from TCPIP.SEZAINST into your proclib, renaming it as
PAGENT.
11.2.2 Create the Policy Agent conguration le
If you do not already run the Policy Agent, you will need to create a conguration le /etc/pagent.conf using
z/OS Unix System Services. If you already run Policy Agent, you will need to nd the existing conguration
le and add the TTLS denitions to it to support Virtel. Sample jobs are provided in the Virtel SAMPLIB
library to assist in performing this step.
Member SSLSETUP
Step PCONFIG in the SSLSETUP sample job contains a starter conguration. The following changes should
be made:
• Replace %virtjob% by the name of your VIRTEL started task (SSLSETUP line 70)
159
Virtel Connectivity Guide, Release 4.58
• Replace 41000-41002 by 41002 in the LocalPortRange parameter (SSLSETUP line 71) to activate
AT-TLS for VIRTEL line C-HTTP
• Replace ServerWithClientAuth by Server in the HandshakeRole parameter (SSLSETUP line 82) as we
will not be using Client Certicates in the initial setup.
11.2.3 Allow the Policy Agent to run during TCP/IP initialization
The Policy Agent must be given READ access to the resource EZB.INITSTACK.* in RACF class SER-
VAUTH. See step EZBAUTH in the SSLSETUP sample job (delivered in VIRTEL SAMPLIB).
11.2.4 Create the server certicate
A server certicate for VIRTEL must be created, signed by a certicate authority, and stored in the RACF
database. In the SSLSETUP sample job we create a signing certicate and use RACF itself as the certicate
authority. Alternatively, you may use an external certicate authority such as Verisign to create and sign
the certicate, then import it into RACF.
At SSLSETUP line 228, replace %virtssl% by the DNS name assigned to the VIRTEL host (for example,
virtssl.syspertec.com)
11.2.5 Add the certicate to the keyring
The server certicate must be added to the Virtel keyring - VIRTRING. See step CCERTIF in the SSLSETUP
sample job.
11.2.6 Allow VIRTEL to access its own certicate
To allow VIRTEL to access its own keyring and server certicate, the VIRTEL started task must have READ
access to the resource IRR.DIGTCERT.LISTRING in the RACF class FACILITY. See step IRRAUTH in
the SSLSETUP sample job.
11.2.7 Activate AT-TLS
To activate AT-TLS, add the following statements to TCPIP PROFILE:
TCPCONFIG TTLS
AUTOLOG 5PAGENT ENDAUTOLOG
Stop and restart TCP/IP to activate the TCPCONFIG TTLS prole statement. The AUTOLOG statement
will cause the PAGENT procedure to be started automatically during TCP/IP initialization.
160 Chapter 11. AT-TLS Secure Session
Virtel Connectivity Guide, Release 4.58
11.3 Operations
11.3.1 Starting the Policy Agent
The AUTOLOG statement in the TCP/IP prole will start the PAGENT procedure automatically at
TCP/IP initialization. Alternatively you can issue the MVS command S PAGENT.
Note: if this is the rst time you have activated the SERVAUTH class, you are likely to see RACF
failure messages during TCP/IP initialization indicating that other applications are unable to access the
resource EZB.INITSTACK. This is normal, because Communications Server uses this mechanism to prevent
applications from accessing TCP/IP before the Policy Agent is started. Do not be tempted to authorize
applications to use this RACF resource. Either ignore the messages (they will go away once PAGENT has
started), or ensure that PAGENT starts before all other applications.
11.3.2 Altering the Policy Agent conguration
To make changes to the Policy Agent conguration le, either edit and resubmit the PCONFIG step of the
SSLSETUP sample job, or use the TSO ISHELL command to edit the le /etc/pagent.conf directly from
ISPF.
After you make changes to the Policy Agent conguration, use the MVS command F PAGENT,REFRESH
to force PAGENT to reread the le.
11.3.3 Logon to VIRTEL using secure session
To access VIRTEL line C-HTTP you must now use URL
https://n.n.n.n:41002 instead of http://n.n.n.n:41002
(where n.n.n.n is the IP address of the z/OS host running VIRTEL).
11.3. Operations 161
Virtel Connectivity Guide, Release 4.58
11.4 Problem determination
11.4.1 Policy Agent log le
Policy Agent startup messages are written to the /tmp/pagent.log le of z/OS Unix System Services. You
can use the TSO ISHELL command to browse this le from ISPF.
11.4.2 Common error messages
Error messages relating to session setup are written to the MVS SYSLOG. The most common error message
is:
EZD1287I TTLS Error RC: nnn event
where nnn represents a return code. Return codes under 5000 are generated by System SSL and
are dened in the System SSL Programming manual. Return codes over 5000 are generated by
AT-TLS and are dened in the IP Diagnosis Guide. Some commonly encountered return codes
are:
7 No certicate
8 Certicate not trusted
109 No certication authority certicates
202 Keyring does not exist
401 Certicate expired or not yet valid
402 or 412 Client and server cannot agree on cipher suite
416 VIRTEL does not have permission to list the keyring
431 Certicate is revoked
434 Certicate key not compatible with cipher suite
435 Certicate authority unknown
5003 Browser sent clear text (http instead of https)
5006 SSL failed to initialize. Check job SSLSETUP.
VIRHT57E LINE IS NOT SET UP FOR HTTPS
Means that the browser sent an https request, but it has not been decrypted by AT-TLS before
being sent to VIRTEL, and VIRTEL has received the message in encrypted format. Normally this
means the AT-TLS rules did not match the incoming request. This is not a Virtel conguration
issue.
EZD1287I TTLS Error RC: 5003
This is the opposite situation. It means that the AT-TLS rules matched the incoming request,
and so AT-TLS was expecting to receive an https request, but it received an http request instead.
Normally AT-TLS is transparent to VIRTEL. AT-TLS performs the decryption and transforms the https
request into an http request before passing it to VIRTEL. The only case where VIRTEL is AT-TLS aware is
when the VIRTEL transaction denition species SECURITY=3 (TLS) and in this case VIRTEL will check
that the session has been processed by AT-TLS and will issue an IOCTL to obtain the userid associated
with the certicate. In the normal case, you should specify HandshakeRole Server, ClientAuthType Full,
and ApplicationControlled O in the AT-TLS rules, as in the example in VIRT447.SAMPLIB(SSLSETUP).
162 Chapter 11. AT-TLS Secure Session
Virtel Connectivity Guide, Release 4.58
VIRTEL does not issue an IOCTL to turn decryption on and o, so if you specied ApplicationControlled
On then you would get VIRHT57E because AT-TLS has not been instructed to start decryption.
If you still get an error when you have ApplicationControlled O then we will need to see the SYSLOG (for
the EZD TTLS messages), the JESMSGLG from the VIRTEL started task, and the SYSPRINT resulting
from a z/OS command F VIRTEL,SNAP immediately after the error occurs. We would also like to see the
exact URL which was entered at the browser, as well as the AT-TLS pagent.conf le.
11.4.3 Verifying AT-TLS is active
To verify that AT-TLS is still activated, you can submit this MVS command:
D TCPIP,,N,TTLS
The response is:
EZD0101I NETSTAT CS V1R12 TCPIP 378 TTLSGRPACTION GROUP ID CONNS VIRTELGROUP 00000002
,→0 1 OF 1RECORDS DISPLAYED END OF THE REPORT
The UNIX command
pasearch
displays the parameters used by PAGENT from /etc/pagent.conf
The TSO command:-
netstat conn
displays active connexions for the VIRTEL STC.
Once a connexion has been established between a client and a Virtel port, the TSO command:-
netstat ttls conn nnnn detail
where nnnn is the identication of the connexion will display the AT-TLS parameters used in the Virtel
connexion.
11.4. Problem determination 163
Virtel Connectivity Guide, Release 4.58
11.5 The Cipher suites
The client and server cipher specications must contain at least one value in common. The TTLSEnviron-
mentAdvancedParms parameter of the Policy Agent conguration le allows you to turn on or o the SSLv2,
SSLv3, and TLSv1 protocols at the server end. The list of supported cipher suites for each protocol is in
the TTLSCipherParms parameter. Check the /tmp/pagent.log le to determine whether any cipher suites
were discarded at startup time.
In Microsoft Internet Explorer, follow the menu Tools – Internet Options – Advanced. Under the security
heading there are three options which allow you to enable or disable the SSL 2.0, SSL 3.0,and TLS 1.0
protocols. You cannot enable or disable individual cipher suites.
In Firefox the cipher specications are accessed by typing about:cong in the address bar and typing security
in the lter box. By default, ssl2 is disabled, and ssl3 and tls are enabled. By default, all weak encryption
cipher suites are disabled, and 128-bit or higher cipher suites are enabled.
11.6 Client certicates
Virtel can extract the userid of a user from a client certicate presented to Virtel during the SSL handshake.
For this to occur the following must be true:-
• The HTTP session is secured using AT-TLS. URL = https://….
• The Policy Agent TTLSConnectionAction or TTLSEnvironmentAction statement contains the param-
eter “HandShakeRole ServerWithClientAuth”
• The client has provided a valid certicate.
• The security subsystem has validate the certicate as belonging to a user.
• The Virtel transaction has Security = 3 dened.
If these conditions are met then the userid contained within the clients digital certicate can be extracted
by Virtel and used in the signon process. In this process it is normal that a PASS Ticket is generated and
associated with the extracted userid.
See the SAMPLIB members SSLSETUP and SSLUCERT for examples on setting up AT-TLS and client
certicates.
164 Chapter 11. AT-TLS Secure Session
Virtel Connectivity Guide, Release 4.58
11.7 Resources
11.7.1 IBM Manuals
-SA22-7683-07 z/OS V1R7 Security Server: RACF Security Administrator's Guide Chapter
,→21. RACF and Digital Certificates
-SC24-5901-04 z/OS V1R6 Cryptographic Services: System SSL Programming Chapter 12.
,→Messages and Codes
-SC31-8775-07 z/OS V1R7 Communications Server: IP Configuration Guide
Chapter 14. Policy-based networking
Chapter 18. Application Transparent Transport Layer Security (AT-TLS) data
,→protection Configuration Reference
Chapter 21. Policy Agent and policy applications
-GC31-8782-06 z/OS V1R7 Communications Server:*IP Diagnosis Guide
Chapter 28. Diagnosing Application Transparent Transport Layer Security (AT-TLS)
-SC31-8784-05 z/OS V1R7 Communications Server: IP Messages: Volume 2(EZB, EZD)
Chapter 10. EZD1xxxx messages
11.7.2 Virtel Material
•TN201407 Pass tickets and supporting Proxy Servers – CA-SiteMinder© & IBM Tivoli WebSeal©
•TN201416 Virtel TLS/SSL Security: Signing on using server and client certicates
11.7. Resources 165
Virtel Connectivity Guide, Release 4.58
166 Chapter 11. AT-TLS Secure Session
CHAPTER
TWELVE
SSO, PASSTICKETS AND PROXY SERVERS
12.1 Introduction
Many businesses now implement products which provide a centralized enterprise-class secure single sign-on
(SSO) and authentication system. The products tend to run on a server(s) and provides access to a business’s
assets like web enabled applications or portals. The basic process is to trap the incoming HTTP call request
and establish some user credentials before llowing access to an asset. For example, the user credentials
can be extracted from the callers request or determined by the callers IP address. The credentials will be
validated against a LDAP or similar active directory server. The result of the validation will either allow
or deny the caller access to the requested asset. Security and asset control is managed by the SSO server
which as a central server can validate credentials to all business assets, be it on the mainframe or other
platforms. Userid and password administration for all assets can be controlled through the functions of the
SSO software employed. Virtel will integrate within this SSO infrastructure and process sign on request once
they have passed validation. Virtel provides its own validation of the SSO server through the use of rules.
In the example that follows we are using CA-Site Minder as an example SSO Server and we will document
how to dene Virtel to interface with the SSO Server and RACF. Our target asset is a CICS application
called SPCICSH. The caller will provide no userid or password data.
Data ow of an SSO session setup
167
Virtel Connectivity Guide, Release 4.58
The initial request is passed through the SSO server. The server will trap and validate the caller. If the
validation is successful a session will be establish between the SSO server and Virtel. Two things to note at
this point. One, the IP address presented to Virtel will be that of the SSO Proxy Server and two, that the
server will modify the HTTP headers to provide addition information, that being the source IP address and
the user id.
A Virtel line trace will reveal these additional headers.
GET /w2h/WEB2SUB.HTML++VirtelSession=AFo0JQAAAAMeuCAo+disconnect=1?pf=DISCONNECT HTTP/
,→1.1
Host: 192.168.170.30:41002
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:27.0) Gecko/20100101 Firefox/27.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,\*/\*;q=0.8
Accept-Language: en-gb,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: http://192.168.170.30:41002/w2h/WEB2AJAX.htm+CICS
Cookie: SYSLANG=en; SYSSTYL=BLUE; SYSPAGE=auto
**SM_User: sptholt <<**
**X-Forwarded-For: 192.168.100.100 <<**
Connection: keep-alive
HTTP/1.1 200 Ok
Server: Virtel/4.53
Date: Wed, 26 Mar 2014 15:31:12 GMT
Content-type: text/html
Content-length: 00000125
<html><head><Meta HTTP-EQUIV="refresh" CONTENT="1; URL=LASTPAGE.HTML"></head>
<body bgcolor="black"><br>
<br>
</body></html>
HTTP/1.0 205 Reset Content
Server: Virtel/4.53
In the above trace the CA-SiteMinder specic header “SM_User” can be seen as identifying the userid and
the X-Forwarded-For:, a standard HTTP header, identies the source IP address. For security reasons this
proxy IP address must be tested for in a VIRTEL rule before the session can be established between the caller
and the asset. There is no password associated with this logon – this will be generated via a passsTicket
request on behalf of the userid identied in the “SM_User” header. The PassTicket will be created as part
of the session setup between Virtel and the asset and on behalf of the caller.
168 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
12.2 Adding headers to the HTTP request
Access the CICS application using FireFox. Use the FireFox “AddIn” Modify Headers to add the headers to
the HTTP request. After adding the headers you will need to “START” the addIn to get the headers added.
Using the Firefox “Modify Headers” addin.
When access the CICS system make sure the “Modify Headers” has started. The ICON should be red.
Modify Header active - red ICON
The following denitions dene what needs to be done to enable a user to log on without specifying a
userid/password to an asset supported by the SSO server. In our example Virtel will logon to a CICS asset
on behalf of the caller using a userid passed by the SSO Proxy and a generated PassTicket. The caller
provides no userid/password information. Once the SSO has validated the callers credential the caller will
be logged on to CICS and will be presented with the following screen:-
12.2. Adding headers to the HTTP request 169
Virtel Connectivity Guide, Release 4.58
Accessing CICS using a callers credentials. No LOGON required.
170 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
12.3 RACF Passtickets
Pass tickets are an alternative to passwords and can greatly improve the security surrounding SSO and
multiple applications access. Passtickets are a dynamically generated password that lasts for approximately
10 minutes. Further information on RACF Passtickets can be found on the web. For the purpose of this
newsletter we will look at the Virtel requirements needed to access our target CICS asset whose RACF APPL
is SPCICSH. Our Virtel task runs under the RACF userid of SPVIRSTC. Here are the RACF denitions
required to support the generation of PassTickets for the target application APPL SPCICSH.
12.3.1 Dene Pass Ticket RACF proles
This job will have to be modied to a customer’s RACF setup. Some proles may already be dened! If
the PERMIT statements do not run then that probably means that some of the RDEFINE entries already
exist in the RACF database - these need to be removed, or an RDELETE added to delete the prole entry,
in order for the job to complete successfully. It should produce a RC=0. See the output in SDSF.
//STEP1 EXEC PGM=IKJEFT1A,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
SETROPTS CLASSACT(APPL)
SETROPTS CLASSACT(PTKTDATA)
SETROPTS RACLIST(PTKTDATA)
SETROPTS GENERIC(PTKTDATA)
RDEFINE FACILITY IRR.RTICKETSERV
RDEFINE PTKTDATA IRRPTAUTH.SPCICSH.\*UACC(NONE)
RDEFINE PTKTDATA SPCICSH SSIGNON(KEYMASKED(998A654FEBCDA123)) +
UACC(NONE)
PERMIT IRR.RTICKETSERV CL(FACILITY) ID(SPVIRSTC) ACC(READ)
PERMIT IRRPTAUTH.SPCICSH.\*CL(PTKTDATA) ID(SPVIRSTC) ACC(UPDATE)
SETROPTS REFRESH RACLIST(PTKTDATA)
SETROPTS REFRESH RACLIST(FACILITY)
Three distinct RACF proles are required to use RACF pass tickets:-
FACILITY IRR.RTICKETSERV * Can use PassTickets *
PTKTDATA IRRPTAUTH.passTicketName. * Let’s VIRETL generate PassTickets on behalf of an
,→application for all users. * or *userid*
PTKTDATA profile_name * APPLNAME used by RACROUTE REQUEST=VERIFY *
Virtel Name correlation
• passTicketName must equal the PassTicket Name dened in the VIRTEL transaction.
• prole_name must equal the VTAM application name dened in the VIRTEL transaction.
These names are normally the same, but they do not have to be.
Note: If you are running separate RACF databases across LPARS the KEYMASKED must be the same
in each RACF database or else the wrong password will be generated and the logon will fail.
12.3. RACF Passtickets 171
Virtel Connectivity Guide, Release 4.58
12.3.2 RACF Proles related to Virtel and Pass Tickets
As mentioned RACF needs to have some proles set up to allow Virtel to use Pass Tickets. The rst prole is
the FACILITY Class prole with the IRR.RTICKETSERV name. The Virtel STC userid must have READ
access to this prole.
RACF prole to allow Virtel to use Pass Tickets
RDEFINE FACILITY IRR.RTICKETSERV
PERMIT IRR.RTICKETSERV CL(FACILITY) ID(SPVIRSTC) ACC(READ)
To allow Virtel to generate Pass Tickets for a particular application we must dene any entry in the PTKT-
DATA class. This entry has the name “IRRPTAUTH.passTicketName.*”” and is a Group Entry. The Virtel
USERID should have update authority to this prole.
172 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
Seting Virtel up with RACF access to PTKTDATA class.
RDEFINE PTKTDATA IRRPTAUTH.SPCICSH.\*UACC(NONE)
PERMIT IRRPTAUTH.SPCICSH.\*CL(PTKTDATA) ID(SPVIRSTC) ACC(UPDATE)
SSIGNON(KEYMASKED(998A654FEBCDA123)) UACC(NONE)
The name in IRRPTAUTH.passTicketName.* prole must match the name in the Virtel Transaction def-
inition. The PassTicket Name is the name of the application as known to RACF for the generation of
Passtickets. This may be dierent to the VTAM application name.
Finally, dene a PTKTDATA prole entry that matches the Virtel Transaction APPLICATION name. In
this case it is SPCICSH. Virtel passes this APPLNAME to RACF via a RACROUTE REQUEST=VERIFY.
12.3. RACF Passtickets 173
Virtel Connectivity Guide, Release 4.58
Setting the Pass Ticket name in the Virtel transaction.
RDEFINE PTKTDATA SPCICSH SSIGNON(KEYMASKED(998A654FEBCDA123)) +
UACC(NONE)
The key thing here is that the PassTicket name must tie up with the generic IRRPTAUTH.SPCICSH.*
entry and the VIRTEL application name must match the descrete PTKTDATA.SPCICSH prole. They can
be the same but needn’t be!
174 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
12.4 Virtel Requirements
12.4.1 Transaction requirements
The Virtel Transaction, under the Entry Point CLIWHOST, will be used to access the CICS asset. It has a
Virtel external name of “CICS”. We modify our transaction to use pass tickets and add a TIOA to logon to
our CICS transaction. The transaction details now look like:-
Modied CICS Virtel transaction to support Pass Tickets.
The PassTicket option is set to 2 and uses the APPL name associated with CICS transaction. Using option
2 means that we do not have to sign onto Virtel rst before generating a PassTicket. Virtel will expect
the Virtel System variable USER to be established. This will be accomplished in an identication scenario
where we have access to the SM_User header value.
The TIOA sign on eld waits for the initial CICS sign on screen to appear and then plugs in the userid (&U)
and PassTicket generated password (&P) into their respective locations. The screen is then “forwarded” to
the CICS application with the USERID and PASSWORDS elds completed.
12.4. Virtel Requirements 175
Virtel Connectivity Guide, Release 4.58
12.4.2 Identication Scenario
To obtain the “SM_User” value and set the userid in the Virtel System USER variable an identication
scenario is used. The following is an example of such a scenario:-
SCENSITE SCREENS APPL=SCENSITE,EXEC=NO
*
* SCENARIO for SiteMinder
*
* The purpose of this scenario is to retrieve the contents of
* the identification headers inserted by the SiteMinder Proxy
*
SCENARIO IDENTIFICATION
*
COPY$ SYSTEM-TO-VARIABLE,VAR='USER', -
FIELD=(TCT-HTTP-HEADER,SM\_USER)
IF$ NOT-FOUND,THEN=NOUSER1
COPY$ VARIABLE-TO-SYSTEM,VAR='USER', -
FIELD=(NAME-OF,USER)
*
EXIT1 DS 0H
SCENARIO END
*
NOUSER1 DS 0H
ERROR$ 0,'SCENSITE ERROR: NO USER VARIABLE'
GOTO$ EXIT1
SCRNEND
END
This SCENARIO has to be set in the Entry Point denition for the line being used. In our case this is the
default Entry Point, CLIWHOST, associated with the external line HTTP-CLI. The following is a snapshot
of the entry point denition:-
176 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
Dening an Identication Scenario in the Virtel Entry Point.
The Identication Scenario eld is lled in with the name of our scenario SCENSITE. This scenario is called
when the inbound call is assigned to an entry point and before any transactions are invoked. The scenario
sets the Virtel system USER variable which will be used in the PassTicket generation.
12.4.3 TCT Considerations
The TCT has to include the following parameters if HTTP User Headers and PassTicket generation is
required. The parameters are:-
HTHEADR=(SM_USER), *
VIRSECU=YES,SECUR=(RACROUTE,RACF), *
RAPPL=FACILITY,RNODE=FACILITY,PRFSECU=SPVIREH, *
PASSTCK=YES, *
The HTHEADR identies the “SM_USER“ as a non standard header and one that Virtel must process.
The PASSTCK keyword enables Virtel to generate PassTickets.
12.4. Virtel Requirements 177
Virtel Connectivity Guide, Release 4.58
12.4.4 Line Rules
To ensure that the source SSO proxy IP address is valid we can code some rules and associate them with
the line. In our example we have coded two sets of rules. The rst one will test the calling proxy IP address.
If that is successful the connection will continue and establish an association with the named Virtel entry
point. If the rst rule fails because the IP address doesn’t match what we expect, the second rule will be
called. This does no more than establish an entry point with a default transaction. The default transaction
will just return an error page to the browser. Here are the two rules that we have associated with our Virtel
line:-
List of rules asssociated with the Virtel line
The second rule is coded as follows:-
178 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
Rule C100PROX to test Proxy IP Address
If the IP address of the SSO Proxy matches the Caller DTE address we have specied in the rule than the
Entry Point CLIWHOST will be associated with line and the transactions dened under that entry point,
CLIWHOST in this case, can be invoked. If the address match fails then the next rule will be called. In our
case this will be rule C999REJ which will invoke transaction EPREJECT, the default transaction for Entry
Point EPREJECT.
Warning: It is important that you use option 3 “STARTS WITH” when dening the Calling DTE
option.
12.4. Virtel Requirements 179
Virtel Connectivity Guide, Release 4.58
Rule C999REJ to reject the session request
This rule does no more than to establish the entry point EPREJECT. EPREJECT will have a default
transaction which just returns an error page to the caller.
180 Chapter 12. SSO, PassTickets and Proxy Servers
Virtel Connectivity Guide, Release 4.58
12.5 Common Errors
Message VIR1502E
VIRTEL does not have sucient access rights to create or validate a passticket allowing user userid at
terminal termed to access application applname. This message is usually preceded by message ICH408I
which shows the name of the resource to which VIRTEL must be granted access.
Action
Examine the SAF and RACF return codes and the RACF reason code to determine the cause. Check
that VIRTEL has access to resource IRR.RTICKETSERV in the FACILITY class, and also to resource
IRRPTAUTH.applname.userid in the PTKTDATA class. The generic resource IRRPTAUTH.** may be
used to permit VIRTEL to generate passtickets for all applications.
For an explanation of the return codes and reason codes, see z/OS Security Server RACF Callable Services
Chapter 2 “R_ticketserv”. Some common codes are:
SAF
RC
RACF
RETC
RACF
Rea-
son
Description
8 8 4 Paramlist error. Ensure that the SCENSITE scenario is available to process the
sm_header.
8 8 16 VIRTEL is not authorized to generate passtickets, or is not authorized to gen-
erate passtickets for this application. See preceding ICH408I message in the
log.
8 16 28 There is no prole in the PTKTDATA class for this application or the PTKT-
DATA class is not active.
12.5. Common Errors 181
Virtel Connectivity Guide, Release 4.58
12.6 Related material
Technical newsletter - TN201416 Virtel Security. Using server and client certicates
182 Chapter 12. SSO, PassTickets and Proxy Servers
CHAPTER
THIRTEEN
RUNNING MULTIPLE INSTANCES OF VIRTEL
13.1 Introduction
For High Availability and performance reasons it is often necessary to run multiple copies of Virtel, preferably
within separate LPARs on separate physical machines. This newsletter discusses the issues raised when
implementing such a setup and how Virtel can exploit the IBM Sysplex technologies. In the following
example there are two instances of Virtel running on separate physical machines sharing the same ARBO
conguration le. The conguration looks like this:-
183
Virtel Connectivity Guide, Release 4.58
Virtel is using several Sysplex technologies to achieve this conguration. For example, Virtel is using VTAM
Generic Resources to facilitate access to the Virtel Administration functions from either instance of Virtel.
VTAM generic resources can be used to distribute workloads across applications that perform the same
task or function. Administration of the ARBO le is through the Virtel Administrator who can logon on
to Virtel using the generic Virtel ACB name VIRTPLEX. This generic ACB enables management of the
ARBO le through either VIRTEL1A or VIRTEL2A. This can be useful, for example, If SYSA was down
for maintenance. VIRTEL administration could still conducted via VIRTEL2A access. No change would be
necessary to any session management tools.
Here are the relevant denitions required to support the VTAM generic resource within Virtel.
13.1.1 VIRTEL TCT Settings
GRNAME=VIRTPLEX, VTAM GENERIC RESOURCE NAME
13.1.2 SYSPLEX denitions
The ISTGENERIC structure will have to be allocated before you can use VTAM generic resources. See the
IBM Network Implementation Guide for further information on conguring the CFRM.
Use the following command to display coupling allocation details for ISTGENERIC.
D XCF,STR,STRNM=ISTGENERIC
VTAM displayof the generic resource
The results from the D NET,ID=VTAMPLEX,E identies the two Virtel instances which are grouped into the
generic resource name VIRTPLEX. The example below shows VIRTEL1A and VIRTEL2A as participating
in the VIRTRPLEX resource name group.
D NET,ID=VIRTPLEX,E
IST097I DISPLAY ACCEPTED
IST075I NAME =VIRTPLEX, TYPE =GENERIC RESOURCE 917
IST1359I MEMBER NAME OWNING CP SELECTABLE APPC
IST1360I SPNET.VIRTEL1A ZAM1SSCP YES NO
IST1360I SPNET.VIRTEL2A ZAM2SSCP YES NO
IST2210I GR PREFERENCE TABLE ENTRY = **DEFAULT**
IST2202I GREXIT =NO WLM =YES LOCLU =YES
IST2204I LOCAPPL =YES PASSOLU =NO
IST314I END
When the VIRTEL*A application is display in VTAM the following messages are written to the console log:-
D NET,ID=VIRTEL1A,E
IST097I DISPLAY ACCEPTED
IST075I NAME =SPNET.VIRTEL1A, TYPE =APPL 925
IST486I STATUS=ACT/S, DESIRED STATE=ACTIV
IST1447I REGISTRATION TYPE =CDSERVR
IST1363I GENERIC RESOURCE NAME VIRTPLEX REPRESENTS SPNET.VIRTEL1A
IST977I MDLTAB=***NA*** ASLTAB=***NA***
IST861I MODETAB=***NA*** USSTAB=***NA***LOGTAB=***NA***
IST934I DLOGMOD=***NA*** USS LANGTAB=***NA***
IST1632I VPACING =7
IST1938I APPC =NO
IST597I CAPABILITY-PLU ENABLED ,SLU ENABLED ,SESSION LIMIT NONE
184 Chapter 13. Running multiple instances of Virtel
Virtel Connectivity Guide, Release 4.58
IST231I APPL MAJOR NODE =APPLVIPX
IST654I I/O TRACE =OFF, BUFFER TRACE =OFF
IST1500I STATE TRACE =OFF
IST271I JOBNAME =SPVIR1A, STEPNAME =SPVIR1A, DSPNAME =ISTEBBDB
IST228I ENCRYPTION =OPTIONAL , TYPE =DES
IST1563I CKEYNAME =VIRTEL1A CKEY =PRIMARY CERTIFY =NO
IST1552I MAC =NONE MACTYPE =NONE
IST1050I MAXIMUM COMPRESSION LEVEL -INPUT =0, OUTPUT =0
IST1633I ASRCVLM =1000000
IST1634I DATA SPACE USAGE: CURRENT =0MAXIMUM =1280
IST171I ACTIVE SESSIONS =0000000001, SESSION REQUESTS =0000000000
IST206I SESSIONS:
IST634I NAME STATUS SID SEND RECV VR TP NETID
IST635I SC0TCP13 ACTIV-S CA7B8B52D125F31F 0003 0001 SPNET
IST314I END
Message IST1363I conrms that VIRTEL operating under the ACB of VIRTEL1A is associated with the
VTAM resource name VIRTPLEX.
13.1. Introduction 185
Virtel Connectivity Guide, Release 4.58
13.1.3 Workload balancing in a SYSPLEX environment
In the following conguration we can see how the VTAM generic resource facility can also be used to distribute
workloads across applications. In this example there are several CICS TOR regions within CICSA, CICSB
and CICSC that are accessed through a VTAM generic resource name or CICSPLEX group name. VIRTEL
uses this name to access the CICS application. The WLM and/or VTAM will distribute sessions across the
members of the CICS generic resource name.
From a High Availability aspect both CICSA and CICSB could both be down and service would still be pro-
vided by CICSC either through VIRTEL1A or VIRTEL2A. In this conguration VIRTEL exploits SYSPLEX
technologies to provide a HA solution. The only VIRTEL requirement is to dene a VIRTEL transaction
which targets CICSZ as the VTAM application, i.e. the VTAM Generic Resource or CICSPLEX group
name.
186 Chapter 13. Running multiple instances of Virtel
Virtel Connectivity Guide, Release 4.58
13.1.4 Sharing the ARBO and other VSAM les
In a SYSPLEX or sharing environment the VSAM les, like the ARBO and TRSF les, must be shared only
in READ mode. To support this the following TCT parameter should be coded:-
VSAMTYP=READONLY
This VIRTCT parameter allows the setup of ‘READ-ONLY’ Virtels, to be used in production or in a Sysplex.
Almost all Virtel VSAM les may be set to read-only mode. (But note that the VIRSWAP le; being a
work le it cannot be read-only.)
If this TCT value is coded then the following changes should also be made to the TCT.
• The MACRF statements should be amended from MACRF=(SEQ,DIR,OUT,LSR) to
MACRF=(SEQ,DIR,LSR).
• The UFILE parameter string should also be changed from 0,10,01 to 0,10,05. For example:-
HTMLTRSF,ACBH2,0,10,01 becomes HTMLTRSF,ACBH2,0,10,05
This will ensure the integrity of the VSAM les across a SYSPLEX or shared environment. When Virtel is
started the following messages will be issued:-
VIR0093I VTAM GENERIC RESOURCE NAME IS VIRTPLEX
VIR0024I OPENING FILE VIRARBO
VIR0024I READ ONLY
VIR0024I OPENING FILE VIRSWAP
VIR0024I OPENING FILE VIRHTML
VIR0024I READ ONLY
VIR0024I OPENING FILE SAMPTRSF
VIR0024I READ ONLY
VIR0024I OPENING FILE HTMLTRSF
VIR0024I READ ONLY
VIR0024I ATTACHING SUBTASKS
Danger: Do not set the SHROPTIONS to (4,3) as this will have undesirable results!
Using a READ only environment enables you to not only share the ARBO le but also the SAMP and
HTML TRSF les.
13.1.5 READ ONLY Restrictions
If you share the VSAM les (SAMP.TRSF, ARBO, HTML.TRSF) in READ only mode Virtel Administration
is not possible. For example uploading web updates to the SAMP.TRSF or adding macros to the DDI
repositories. In this conguration you will have to have a maintenace instance of Virtel which can write to
the VSAM les. This can be brought up during a maintenace slot when the READ ONLY instances are
down. An alternative to this method is to maintain a copy of the VSAM les and use these for maintenace
and updates then copy these VSAM les to the READ ONLY versions during a maintenace slot.
In Virtel V4.58 this restriction has been removed with the introduction of the VIRPLEX feature. VIRPLEX
enables a nominated “WRITER” Virtel task to particpate in the Virtel infrastrure. Only administrators
would have access to this “WRITER” instance. Maintenance and centralized entities, such as macros, could
be uploaded using the “WRITER” instance. The “writer” instance, which has “write access” to the Virtel
les would then populate the les with the new updates. Virtel “READ” instances would detect the changes
and automatically refresh the “cache” instances. See the “VIRPLEX section”, for move information.
13.1. Introduction 187
Virtel Connectivity Guide, Release 4.58
13.1.6 Virtel naming conventions
When running more than one VIRTEL STC care must be taken when dening the VTAM relay names that
each VIRTEL tasks will use. In the above conguration each Virtel instance is running on a dierent LPAR,
and for the HA reasons, probably on a dierent physical machine; however, the VTAM names employed must
be unique. With Virtel you can dene a single conguration within the ARBO and TCT which contains a
unique pool of Virtel relays for each Virtel instance.
Here are two possible ways to dene the relay pools for multiple Virtel instances:
The rst way is to include the SYSCLONE value as part of the LU name. The relay denitions utilize
the system symbolic SYSCLONE value in the IEASYMxx member of PARMLIB. The clone value is taken
from the system symbolic &SYSCLONE and is identied in the VIRTEL denitions through the + (plus)
character:
LIST of TERMINALS ---------------------------------- Applid: VIRTEL1A 15:11:01
Terminal Repeated Relay   Entry    Type  I/O Pool   2nd Relay
CLLOC000 0050 33
CLVTA000 0080   *W2HPOOL        33
DELOC000 0010 33
DEVTA000 0016   *W2HPOOL        33
W2HIM000 0080 R+IM00011
W2HTP000 0080 R+VT00033 *W2HPOOL R+IM000
13.1.7 TCT denition
In the conguration above there are two Virtel STCs running on dierent LPARS whose &SYSCLONE
values are 1A and 2A. With the same TCT being used for both VIRTEL1A and VIRTEL2A the following
is specied in the common TCT:-
APPLID=VIRTEL+,
SYSPLUS=YES,
This will means that the two Virtels STCs will have a VTAM APPLID of^VIRTEL1A and VIRTEL2A. The
Virtel relay LU names are R1AVT000-079 for LPAR 1A, and R2AVT000-079 for LPAR 2A. The VTAM
denition to support this conguration would like:-
APPLVIPX VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
* Product : VIRTEL *
* Description : APPL for VIRTEL SYSPLEX (SPVIR1A and SPVIR2A) *
* ------------------------------------------------------------------ *
VIRTEL&SYSCLONE APPL EAS=160,AUTH=(ACQ,BLOCK,PASS,SPO), *
ACBNAME=VIRTEL&SYSCLONE
* ------------------------------------------------------------------ *
* R&SYSCLONEVTxxx : VTAM application relays for VIRTEL Web Access *
* ------------------------------------------------------------------ *
R&SYSCLONE.VT??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM, *
DLOGMOD=SNX32702,EAS=1
* ------------------------------------------------------------------ *
* R&SYSCLONEIMxxx : Printer relays for VIRTEL Web Access terminals *
* ------------------------------------------------------------------ *
R&SYSCLONE.IM??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM, *
DLOGMOD=SCS,EAS=1
R&SYSCLONE.IP??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM, *
DLOGMOD=DSILGMOD,EAS=1
188 Chapter 13. Running multiple instances of Virtel
Virtel Connectivity Guide, Release 4.58
Because this naming convention could be constraining if you want to use 4-character LU names, there is a
second method which allows you to freely choose the LU names without the need to include the SYSCLONE
characters as part of the LU name. In the next example two pools are dened. Pool *W1APOOL has relay
names J000-J999, K000-K999, L000-L999 for LPAR 1 (with printer names Pnnn,Qnnn,Rnnn), and pool
*W2APOOL has relay names M000-M999, N000-N999, O000-O999 (with printer names Snnn,Tnnn,Unnn)
for LPAR 2:-
Terminal Repeated Relay   Entry    Type  I/O Pool   2nd Relay
CLLOC000 0500 33
CLVTA000 1000   *W+POOL33
CLVTB000 1000   *W+POOL33
CLVTC000 1000   *W+POOL33
DELOC000 0010 33
DEVTA000 0016   *W+POOL33
W2HIP000 1000 P00011
W2HIQ000 1000 Q00011
W2HIR000 1000 R00011
W2HIS000 1000 S00011
W2HIT000 1000 T00011
W2HIU000 1000 U00011
W2HTJ000 1000 J00033 *W1APOOL P000
W2HTK000 1000 K00033 *W1APOOL Q000
W2HTL000 1000 L00033 *W1APOOL R000
W2HTM000 1000 M00033 *W2APOOL S000
W2HTN000 1000 N00033 *W2APOOL T000
W2HTO000 1000 O00033 *W2APOOL U000
The VTAM denitions would be similar to those from the previous example except the &SYSCLONE would
be replaced by the relay characters.
APVIRT&SYSCLONE. VBUILD TYPE=APPL
* ------------------------------------------------------------------*
*Product:VIRTEL*
* Description : Main ACB for VIRTEL application *
* ------------------------------------------------------------------*
VIRTEL&SYSCLONE APPL AUTH=(ACQ,BLOCK,PASS,SPO),EAS=160, +
      ACBNAME=VIRTEL&SYSCLONE
* ------------------------------------------------------------------*
* Jxxx,Kxxx  : VTAM application relays for VIRTEL Web Access*
* Lxxx,Mxxx  : VTAM application relays for VIRTEL Web Access *
* Nxxx,Oxxx  : VTAM application relays for VIRTEL Web Access*
* ------------------------------------------------------------------*
J??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
K??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
L??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
M??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
N??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
O??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
* ------------------------------------------------------------------*
* Pxxx,Qxxx  : Printer relays for VIRTEL Web Access terminals *
* Rxxx,Sxxx  : Printer relays for VIRTEL Web Access terminals *
* Txxx,Uxxx  : Printer relays for VIRTEL Web Access terminals   *
* ------------------------------------------------------------------*
P??? APPL AUTH=NVPACE,EAS=1,PARSESS=NO,MODETAB=ISTINCLM,SESSLIM=YES
Q??? APPL AUTH=NVPACE,EAS=1,PARSESS=NO,MODETAB=ISTINCLM,SESSLIM=YES
R??? APPL AUTH=NVPACE,EAS=1,PARSESS=NO,MODETAB=ISTINCLM,SESSLIM=YES
S??? APPL AUTH=NVPACE,EAS=1,PARSESS=NO,MODETAB=ISTINCLM,SESSLIM=YES
T??? APPL AUTH=NVPACE,EAS=1,PARSESS=NO,MODETAB=ISTINCLM,SESSLIM=YES
13.1. Introduction 189
Virtel Connectivity Guide, Release 4.58
U??? APPL AUTH=NVPACE,EAS=1,PARSESS=NO,MODETAB=ISTINCLM,SESSLIM=YES
190 Chapter 13. Running multiple instances of Virtel
Virtel Connectivity Guide, Release 4.58
13.2 Using a Distributed VIPA to load balance
Using a Dynamic VIPA with IBM’s SYSPLEX Distributor (SD) you can balance Virtel session workload
across more than one Virtel STC. The distributing TCPIP stack will balance workload across the partici-
pating target TCPIP stacks. Allocation of new sessions on the IP side will depend on the selected SD/WLM
algorithm. For example this can be a Round Robin policy or WLM policy workload algorithm. Access
to the Virtel tasks is through using distributed VIPA address which is dened in a TCPIP prole. In the
conguration above it is dened as 192.168.170.15. The relevant PROFILE denitions for TCPIP would
look like:-
VIPADYNAMIC
VIPARANGE DEFINE MOVEABLE NONDISRUPTIVE 255.255.255.0 192.168.170.20
VIPADEFINE MOVE IMMED 255.255.255.0 192.168.170.15
VIPADISTRIBUTE DEFINE TIMEDAFF 60 DISTMETHOD ROUNDROBIN 192.168.170.15
DESTIP ALL
ENDVIPADYNAMIC
13.2.1 Session Anity
It is essential to include the TIMEDAFF parameter in the VIPA denition as this maintains session anity.
The TIMEDAFF facility ensures that a user will always connect to the same VIRTEL while a session is
open. Also, it is recommended that the Virtel line W-HTTP (port 41001) is used for Virtel Administration
and line C-HTTP (port 41002) for user access to applications.
Line W-HTTP should be dened using the base address of the LPAR (i.e.the home address of the default
interface) by specifying only the port number. For example:
Local ident ==> :41001
Line C-HTTP should be dened using the distributed VIPA address and port number if you are using a
dynamic VIPA:
Local ident ==> 192.168.170.15:41002
If you are not using a dynamic VIPA to point to your Virtel then the port address must be prexed with 0
or 0.0.0.0. For example:-
Local ident ==> 0:41002
This will ensure the Virtel doesn’t associate itself with a particular IP address.
The Virtel Line display command displays this conguration:
F SPVIR1A,LINES
VIR0200I LINES
VIR0201I VIRTEL 4.54 APPLID=VIRTEL1A LINES
VIR0202I INT.NAME EXT.NAME TYPE ACB OR IP
VIR0202I -------- -------- ----- ---------
VIR0202I C-HTTP HTTP-CLI TCP1 192.168.170.15:41002
VIR0202I W-HTTP HTTP-W2H TCP1 :41001
VIR0202I ---END OF LIST---
In this way the administrator can access a specic Virtel using port 41001 of the appropriate LPAR’s IP
address, while the users can access both Virtels using port 41002 on the DVIPA address.
13.2. Using a Distributed VIPA to load balance 191
Virtel Connectivity Guide, Release 4.58
13.3 Using an Apache Proxy to load balance
Another way of balancing workloads across multiple Virtel instances is through an Apache Reverse Proxy
Server. In this setup the proxy server load balances IP sessions across the known TCPIP stacks, very much
like IBM’s Sysplex Distributor.
Again, to maintain session anity the correct load balancing parameters must be used. An example from
the http.conf looks like this:-
#
# Virtel
#
ProxyPass /balancer://hostcluster/
ProxyPassReverse /balancer://hostcluster/
<Proxy balancer://hostcluster>
BalancerMember http://syt00101.gzaop.local:41002 retry=5
BalancerMember http://syt00101.gzaop.local:51002 retry=5
ProxySet lbmethod=byrequests
</Proxy>
For more information on setting up an Apache Proxy Server visit http://httpd.apache.org/docs/2.2/mod/
mod_proxy_balancer.html
To use Apache as a Proxy Server it is essential that the correct conguration modules are loaded at startup.
Here is an example:-
#LoadModule foo_module modules/mod_foo.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authz_user_module modules/mod_authz_user.so
#LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule include_module modules/mod_include.so
192 Chapter 13. Running multiple instances of Virtel
Virtel Connectivity Guide, Release 4.58
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
#LoadModule mime_magic_module modules/mod_mime_magic.so
#LoadModule expires_module modules/mod_expires.so
LoadModule headers_module modules/mod_headers.so
LoadModule unique_id_module modules/mod_unique_id.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
#LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule mime_module modules/mod_mime.so
#LoadModule dav_module modules/mod_dav.so
#LoadModule dav_fs_module modules/mod_dav_fs.so
LoadModule autoindex_module modules/mod_autoindex.so
#LoadModule asis_module modules/mod_asis.so
#LoadModule info_module modules/mod_info.so
LoadModule cgi_module modules/mod_cgi.so
LoadModule dir_module modules/mod_dir.so
LoadModule actions_module modules/mod_actions.so
#LoadModule speling_module modules/mod_speling.so
#LoadModule userdir_module modules/mod_userdir.so
LoadModule alias_module modules/mod_alias.so
#LoadModule rewrite_module modules/mod_rewrite.so
#LoadModule deflate_module modules/mod_deflate.so
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
Some other Apache conguration recommendations are:-
*Timeouts
SSLDisable
SSLV3Timeout 18010
*Format log with router information
LogFormat "%h %l %u %t\"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" \"%{BALANCER_
,→WORKER_ROUTE}e\""combined
*set Max-Age to 12h (doesn't work with IE) or
*enable mod_expires and set: (this should be checked)
ExpiresActive On
ExpiresDefault "access plus 16 h"
See https://httpd.apache.org/docs/2.2/mod/mod_expires.html for more information.
13.3. Using an Apache Proxy to load balance 193
Virtel Connectivity Guide, Release 4.58
194 Chapter 13. Running multiple instances of Virtel
CHAPTER
FOURTEEN
VIRPLEX
Virplex
The new Virplex communication feature of Virtel provides the ability for multiple virtel instances to com-
municate with each other. This global knowledge of participating Virtel instances is referred to as a Virplex
and enables Virtel instances to share the same ARBO and TRSF les. In a Virplex there is a number of
Virtel “READ ONLY” instances and one “WRITER” instance. These instances all share the same ARBO
and TRSF les, including any user dened TRSF les, with the read only instances only have a “READ”
capability on the shared VSAM les and the “WRITER” instance having a standard tandard read/write ca-
pability to all les. The ability to share les amongst participating Virtels provides support for the following
functions:
Dynamic Message Routing Removes the dependency of external “Timed Anity” technologies to support
session anity between a Virtel instance and browser session. Changes in the URL format now enable
participating Virtels within the Virplex to determine whether they are the target of the URL or if the
URL belongs to another Virtel instance. In the latter case the URL is forwarded onto the target Virtel
destination. A unique Virplex token is attached to each URL request which provides the anity between a
Virtel instance and browser session. This feature provides additional support in customer’s High Availability
scenarios/implementations.
Dynamic Cache Updates Within a Virplex environment maintenance can now be distributed to all participat-
ing instances through the “WRITER” instance. This feature enables maintenance updates to be populated
to each Virtel’s internal cache system without the need to recycle a Virtel instance. The sequence of events
would be as follows:-
• Virtel maintenance is uploaded, via the “Writer” task, to the SAMP.TRSF VSAM le.
• The “WRITER” tasks then contacts each participating “READER” tasks to inform them that their
internal cache is no longer in sync.
• The “Reader” instance resynchronizes their “internal cache” with the TRSF le thereby dynamically
refreshing the browsers cache and introducing the new maintenance.
Central User Parameter Repository Using the features of Virplex users can now maintain a centralized
repository for user’s VWA settings across multiple instances of Virtel. This repository keeps each users
settings so that when a new browser session is initiated the same settings will be used. Previously settings
were only maintained in local storage and were lost when moving to a dierent browser or device. Now the
local storage is synchronized with the central repository enabling the user to maintain the same settings
across dierent environments.
195
Virtel Connectivity Guide, Release 4.58
14.1 Setting up a Virplex
14.2 TCT denitions
Setting up a Virplex involves two TCTs, one for the ‘READER’ instances and another for the ‘WRITER’
instance. There can be multiple ‘READER’ instances but only one ‘WRITER’ instance.
14.2.1 TCT for ‘READER’ tasks.
The TCT for ‘READER’ tasks must have the following TCT denitions:-
VSAMTYP=READONLY, Set Read only.Default =Read/Write
IGNLU=W-HTTP, Disable the Admin line
196 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
. . .
UFILE1=(SAMPTRSF,ACBH1,0,10,05), ACBHx fields set accordingly.Note 05
UFILE2=(HTMLTRSF,ACBH2,0,10,05), and not 01.
. . .
ACBH1 ACB AM=VSAM,DDNAME=SAMPTRSF,MACRF=(SEQ,DIR), *
STRNO=3OUT option removed
ACBH2 ACB AM=VSAM,DDNAME=HTMLTRSF,MACRF=(SEQ,DIR), *
STRNO=3OUT option removed
14.2.2 TCT for ‘WRITER’ task
The TCT for a ‘WRITER’ task must have the following denitions in the TCT.
VSAMTYP=WRITER, Set Writer Instance
IGNLU=C-HTTP, Disable any user line
. . .
UFILE1=(SAMPTRSF,ACBH1,0,10,05), ACBHx fields set to 05 and not 01.
UFILE2=(HTMLTRSF,ACBH2,0,10,05),
. . .
ACBH1 ACB AM=VSAM,DDNAME=SAMPTRSF,MACRF=(SEQ,DIR), *
STRNO=3
ACBH2 ACB AM=VSAM,DDNAME=HTMLTRSF,MACRF=(SEQ,DIR), *
STRNO=3
14.3 ARBO denitions
To support a Virplex each Virtel instance must be aware of all instances within the Virplex. This internal
communication is provide by dening Virtel lines between each instance. These lines are dened in a
common ARBO le shared by all members of a Virplex. The communications protocol used between Virplex
members is the proprietary QUICKLNK protocol. In the following sample denitions the W-HTTP line is
the administration port only available to the ‘WRITER’ task and the common user line, V-HTTP provides
the common port for the Virtel instances within the Virplex.
QLNK Line denitions for ‘READER’ instances.~
*QLNK Lines for Virplex Reader tasks.
LINE ID=SPVIRE00,
NAME=SPVIRE00,
LOCADDR=192.168.170.81:41030,
DESC='Virplex READ ONLY instance - SPVIRE00',
TYPE=TCP1,
INOUT=3,
PROTOCOL=QUICKLNK,
TIMEOUT=0000,
ACTION=0,
WINSZ=0000,
PKTSZ=0000,
RETRY=0000
The ID and Name keywords must refer to the instances VTAM ACB name. The address in the LOCADDR
must be unique within the Virplex.
QLNK Line denition for ‘WRITER’ instance.
14.3. ARBO denitions 197
Virtel Connectivity Guide, Release 4.58
*QLNK Lines for Virplex Writer tasks
LINE ID=SPVIRE99, -
NAME=SPVIRE99, -
LOCADDR=192.168.170.81:41099, SHARED PORT -
DESC='Virplex READ/WRITE instance - SPVIRE99',-
TERMINAL=VX, -
TYPE=TCP1, -
INOUT=3,-
PROTOCOL=QUICKLNK, -
TIMEOUT=0000,-
ACTION=0,-
WINSZ=0000,-
PKTSZ=0000,-
RETRY=0000
The ID and Name keywords must refer to the WRITER’s VTAM ACB name. The address in the LOCADDR
must be unique within the Virplex. The WRITER task also requires additional terminal denitions –
TERMINAL=VX.
Terminal denitions for ‘WRITER’ instance.
TERMINAL ID=VXLOC000, -
DESC='HTTP terminals (no relay)',-
TYPE=3,-
COMPRESS=2,-
INOUT=3,-
STATS=26,-
REPEAT=0010
Modications to existing lines will also be required. Assuming that the ‘WRITER’ line will be using line
W-HTTP to communicate with the ‘READER’ instances, and the C-HTTP line will be associated with the
‘READER’ instances serving incoming calls, the following changes are required.
Virtel lines for Administration (W-HTTP) and user access (V-HTTP).
In both the V-HTTP and W-HTTP line denitions, the COND=’VIRPLEX-LINE(=VIRTEL=)’ parameter
must be added. Here is an example of the revised denition for W-HTTP.
Administration line associated with the ‘WRITER’ task.
*UPDATE W-HTTP WITH COND=
LINE ID=W-HTTP, -
NAME=HTTP-W2H, -
LOCADDR=:41001,-
DESC='HTTP line (entry point WEB2HOST)',-
TERMINAL=DE, -
ENTRY=WEB2HOST, -
TYPE=TCP1, -
INOUT=1,-
COND='VIRPLEX-LINE(=VIRTEL=)',-
PROTOCOL=VIRHTTP, -
TIMEOUT=0000,-
ACTION=0,-
WINSZ=0000,-
PKTSZ=0000,-
RETRY=0010
The user interface line denition, V-HTTP, looks like this:-
198 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
*
*User line associated with Virplex VIPA 15.41902 *
*
LINE ID=V-HTTP, -
NAME=HTTP-VPX, -
LOCADDR=192.168.170.15:41902,-
DESC='HTTP line (Entry point VPXWHOST)',-
TERMINAL=VP, -
ENTRY=VPXWHOST, -
COND='VIRPLEX-LINE(=VIRTEL=)',
TYPE=TCP1, -
INOUT=1,-
PROTOCOL=VIRHTTP, -
TIMEOUT=0000,-
ACTION=0,-
WINSZ=0000,-
PKTSZ=0000,-
RETRY=0010
*
Terminal denitions to support user interface on common port 41902.
*
TERMINAL ID=VPLOC000, -
DESC='HTTP terminals (no relay) - V-HTTP',-
TYPE=3,-
COMPRESS=2,-
INOUT=3,-
STATS=26,-
REPEAT=0080
Entry point denition for VPXHOST
*
ENTRY ID=VPXWHOST, -
DESC='HTTP entry point for Virplex line)',-
TRANSACT=VPX, -
TIMEOUT=0720,-
ACTION=0,-
EMUL=HTML, -
SIGNON=VIR0020H, -
MENU=VIR0021A, -
IDENT=SCENLOGM, -
EXTCOLOR=E
Pool denitions
*
TERMINAL ID=VPXIM000, -
RELAY=R+IM000, -
DESC='SCS printers (LUTYPE1) for HTTP',-
TYPE=S, -
COMPRESS=2,-
INOUT=1,-
STATS=26,-
REPEAT=0010
TERMINAL ID=VPXTP000, -
RELAY=R+VT000, -
14.3. ARBO denitions 199
Virtel Connectivity Guide, Release 4.58
POOL=*VPXPOOL, -
DESC='Relay pool for HTTP',-
RELAY2=R+IM000, -
TYPE=3,-
COMPRESS=2,-
INOUT=3,-
STATS=26,-
REPEAT=0010
Terminal relay denitions
*
TERMINAL ID=VPVTA000, -
RELAY=*VPXPOOL, -
DESC='HTTP terminals (with relay)',-
TYPE=3,-
COMPRESS=2,-
INOUT=3,-
STATS=26,-
REPEAT=0010
Note the use of the + in the relay names. This will be overwritten with the clone parameter in the startup
JCL for the ‘READER’ tasks.
Transaction denitions
These transactions are required to support Virtel and Applications in a Virplex.
*Virtel Internal transactions
TRANSACT ID=VPX-00,
NAME=VPXWHOST,
DESC='Default directory = entry point name',
APPL=VPX-DIR,
TYPE=4,
TERMINAL=VPLOC,
STARTUP=2,
SECURITY=0,
TIOASTA='/w2h/appmenu.htm+applist'
TRANSACT ID=VPX-03W,
NAME='w2h',
DESC='W2H toolkit directory (/w2h)',
APPL=W2H-DIR,
TYPE=4,
STARTUP=2,
SECURITY=0
TRANSACT ID=VPX-03X,
NAME='vpx',
DESC='VPX directory (/vpx)',
APPL=VPX-DIR,
TYPE=4,
STARTUP=2,
SECURITY=0
TRANSACT ID=VPX-03Y,
NAME='yui',
DESC='YUI toolkit directory (/yui)',
APPL=YUI-DIR,
TYPE=4,
STARTUP=2,
SECURITY=0
200 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
TRANSACT ID=VPX-90,
NAME='applist',
DESC='List of applications for appmenu.htm',
APPL=VIR0021S,
TYPE=2,
TERMINAL=VPLOC,
STARTUP=2,
SECURITY=1
TRANSACT ID=W2H-80X,
NAME='uplvpx',
DESC='Upload macros (VPX-DIR directory)',
APPL=VIR0041C,
TYPE=2,
TERMINAL=DELOC,
STARTUP=2,
SECURITY=1,
LOGMSG=VPX-DIR
These transactions dene the 3270 applications.
TRANSACT ID=VPX-14, NAME=TSO, DESC=’Logon to TSO’, APPL=TSO, TYPE=1,
TERMINAL=VPVTA, STARTUP=1, SECURITY=1
TRANSACT ID=VPX-15, NAME=CICS, DESC=’Logon to CICS’, APPL=SP-
CICST, TYPE=1, TERMINAL=VPVTA, STARTUP=1, SECURITY=1,
TIOASTA=”Signon&/F&*7D4EC9&‘114BE9’&U&‘114CF9’&P&/A”
Sub directory denition for VIR-DIR
*
SUBDIR ID=VPX-DIR,
DESC='Pages for VPXWHOST',
DDNAME=HTMLTRSF,
KEY=VPX-KEY,
NAMELEN=0064,
AUTHUP=X,
AUTHDOWN=X,
AUTHDEL=X
Virplex JCL examples
JCL Procedure for Virplex.
//**********************************************************************
//* DEFAULT PROCEDURE FOR A VIRPLEX TASK *
//**********************************************************************
//VIRPLEX PROC QUAL=&HLQ..VIRT&REL,
// TCT=00, READ ONLY TCT (99 =R/W)
// PROG=VIR6000, PROGRAM TO CALL
// CLONE=00, APPLID=SPVIRE&CLONE
// IP=192.168.170.48 Not Used
//VIRTEL EXEC PGM=&PROG,
// TIME=1440,REGION=0M,
// PARM='&TCT,SPVIRE&CLONE,,&IP,&CLONE'
//STEPLIB DD DSN=&QUAL..LOADLIB,DISP=SHR
//DFHRPL DD DSN=&QUAL..LOADLIB,DISP=SHR
//SERVLIB DD DSN=&QUAL..SERVLIB,DISP=SHR
//* VSAM FILES SHARED
//VIRARBO DD DSN=&QUAL..VIRPLEX.ARBO,DISP=SHR
14.3. ARBO denitions 201
Virtel Connectivity Guide, Release 4.58
//SAMPTRSF DD DSN=&QUAL..VIRPLEX.SAMP.TRSF,DISP=SHR
//HTMLTRSF DD DSN=&QUAL..VIRPLEX.HTML.TRSF,DISP=SHR
//* VSAM FILES UNIQUE
//VIRHTML DD DSN=&QUAL..VIRTEL&CLONE..HTML,DISP=SHR
//VIRSWAP DD DSN=&QUAL..VIRTEL&CLONE..SWAP,DISP=SHR
//* NVSAM
//SYSOUT DD SYSOUT=*
//VIRLOG DD SYSOUT=*
//VIRTRACE DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
JCL example for Virtel ‘READER’ task 0
//SPTHOLT0 JOB 9000,'VIRTEL',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//PROCLIB JCLLIB ORDER=SPTHOLT.VIRT458.CNTL
//S01 EXEC VIRTELZ,TCT=00,HLQ=SPTHOLT,REL=458,CLONE=00
JCL example for Virtel ‘READER’ task 1
//SPTHOLT1 JOB 9000,'VIRTEL',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//PROCLIB JCLLIB ORDER=SPTHOLT.VIRT458.CNTL
//S01 EXEC VIRTELZ,TCT=00,HLQ=SPTHOLT,REL=458,CLONE=01,
// IP=192.168.170.47
JCL example for Virtel ‘WRITER’ task
//SPTHOLT9 JOB 9000,'VIRTEL',CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID
//PROCLIB JCLLIB ORDER=SPTHOLT.VIRT458.CNTL
//S01 EXEC VIRTELZ,TCT=99,HLQ=SPTHOLT,REL=458,CLONE=99,
// IP=192.168.170.39
VTAM Denitions
VTAM denitions required for Virtel ‘Reader’ task 0. In this example, a separate VTAMLST member
would be require for each Virtel instance within the Virplex to support clone values of 00(RO) , 01(RO) and
99(RW). These VTAM denitions could be merged into one member.
VIRTEH00 VBUILD TYPE=APPL
* ------------------------------------------------------------------ *
* Product : VIRTEL *
* Description : Definitions for a VIRTEL VIRPLEX instance *
* ------------------------------------------------------------------ *
SPVIRE00 APPL EAS=160,AUTH=(ACQ,BLOCK,PASS,SPO),ACBNAME=SPVIRE00
* ------------------------------------------------------------------ *
* R00VTxxx : VTAM application relays for VIRTEL Web Access *
* ------------------------------------------------------------------ *
R00VT??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SNX32702,EAS=1
* ------------------------------------------------------------------ *
* R00IMxxx : Printer relays for VIRTEL Web Access terminals *
* ------------------------------------------------------------------ *
R00IM??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=SCS,EAS=1
R00IP??? APPL AUTH=(ACQ,PASS),MODETAB=ISTINCLM,DLOGMOD=DSILGMOD,EAS=1
TCPIP Changes The TCPIP prole denition requirements for a VIRPLEX are a shared Port address
and a common VIPA for the Sysplex Distributor.
202 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
Shared Port Example
; SPVIRExx User Range for Virplex
41902 TCP SPVIRE00 SHAREPORT ; Virtel Portshare
41902 TCP SPVIRE01 ; Virtel Portshare
Common VIPA address
;192.168.170.15 VIPA for SPVIRExx distribution tests
VIPADYNAMIC
VIPARANGE DEFINE MOVEABLE NONDISRUPTIVE 255.255.255.0 192.168.170.20
VIPADEFINE MOVE IMMED 255.255.255.0 192.168.170.15
VIPADISTRIBUTE DEFINE TIMEDAFF 300 DISTMETHOD ROUNDROBIN 192.168.170.15
DESTIP ALL
ENDVIPADYNAMIC
Installation overview to get Virplex up and running.
The following guide is based upon the examples given in this document. Here the objective is to set up
three Virtel batch instances, two reader instances (SPTHOLT0 and SPTHOLT1), and one writer instance,
SPTHOLT9. The examples used are maintained in the VIRTEL.SAMPLIB. The instances are runs as batch
jobs - SPTHOLT0(SPVIRE00), SPTHOLT1(SPVIRE01) and SPTHOLT9(SPVIRE99).
Install Virtel and get base product up and running before attempting any Virplex changes.
SAMPLIB Members: VIRPLEX, VIRTCT00, VIRTCT99, VIRTELZ, VIRTEL00, VIRTEL01,
,→VIRTEL99
• Allocate common VSAM libraries and copy the SAMP, ARBO and HTML from existing/installation
libraries.
• Allocate unique libraries for VIRHTML and VIRSWAP. If you are collecting statistics then VIRSTAT
also has to be allocated as is unqiue to each Virtel instance.
• Updated you VTAMLST library to support each instance. Each instance will use VTAM resource
names based upon the CLONE= keyword in the startup JCL. Activate VTAMLST members.
• Customize TCT VIRTCT00 ( Reader TCT). Update license and other details.
• Customize TCT VIRTCT99 (Writer TCT). Update license and other details.
• Customize the JCL members VIRPLEX, VIRTELZ, VIRTEL00, VIRTEL01 and VIRTEL99
• Activate TCPIP changes – V TCPIP„O,DSN=TCPIP.TCPPARMS(VIRTPROF)
• Update the sample VIRPLEX denitions to support your environment.
• Run the VIRPLEX job. This will perform the following steps:- Allocate unique VSAM les Allocate
shared VSAM les Copy VSAM les from install or “existing” user les. Update the VIRPLEX ARBO
with the denitions required to support a Virplex. Assemble to ‘READER’ and ‘WRITER’ TCT’s
• Start the ‘WRITER’ task by submitting Job VIRTEL99.
You should see the following messages as the Administration line is activated:-
VIRHT01I HTTP INITIALISATION FOR HTTP-W2H (W-HTTP ), VERSION 4.58
VIRT905I HTTP-W2H SOCKET 00000000 LISTENING 192.168.170.039:41001
VIRHT02I LINE HTTP-W2H (W-HTTP ) HAS URL http://192.168.170.39:41001
VIRHT03I HTTP LINE HTTP-W2H (W-HTTP ), IS A VIRPLEX SERVER WITH VSAMTYP=WRITER
The Administration portal can be access via URL 192.168.170.39:41001. Ignore any CONNECT error mes-
sages. This is normal at this stage.
• Start the ‘READER’ tasks by submitting jobs VIRTEL00 and VIRTEL01
14.3. ARBO denitions 203
Virtel Connectivity Guide, Release 4.58
In the ‘WRITER’ task you should see evidence that the ‘WRITER’ has connected to the ‘READER’ tasks:-
VIRB17AI LINE SPVIRE00 (SPVIRE00), RESTARTED TO ALLOW CONNECTION TO SPVIRE00
VIRQLK9I INITIALISATION FOR SPVIRE00 (SPVIRE00), VERSION 4.58
VIRT907I SPVIRE00 SOCKET 00000000 CALLING 192.168.170.081:41030
VIRQLK8I LOCAL LINE SPVIRE00 (SPVIRE00) IS CONNECTED TO REMOTE VIRTEL : SPVIRE00
VIRQLK9I INITIALISATION FOR SPVIRE01 (SPVIRE01), VERSION 4.58
. . .
VIRB17AI LINE SPVIRE01 (SPVIRE01), RESTARTED TO ALLOW CONNECTION TO SPVIRE01
VIRQLK9I INITIALISATION FOR SPVIRE01 (SPVIRE01), VERSION 4.58
VIRT907I SPVIRE01 SOCKET 00000000 CALLING 192.168.170.081:41031
VIRQLK8I LOCAL LINE SPVIRE01 (SPVIRE01) IS CONNECTED TO REMOTE VIRTEL : SPVIRE01
In the ‘READER’ tasks you should see evidence that the ‘READER ’ has connected to the ‘WRITER’ tasks:-
SPTHOLT0 Connecting to the ‘WRITER’ task SPTHOLT9 and the other ‘READER’ tasks SPTHOLT1
VIRQLK9I INITIALISATION FOR SPVIRE99 (SPVIRE99), VERSION 4.58
VIRT907I SPVIRE99 SOCKET 00000000 CALLING 192.168.170.081:41099
VIRQLK8I LOCAL LINE SPVIRE99 (SPVIRE99) IS CONNECTED TO REMOTE VIRTEL : SPVIRE99
. . .
VIRT905I HTTP-VPX SOCKET 00000000 LISTENING 192.168.170.015:41902
VIRHT02I LINE HTTP-VPX (V-HTTP ) HAS URL http://192.168.170.15:41902
VIRHT03I HTTP LINE HTTP-VPX (V-HTTP ), IS A VIRPLEX SERVER WITH VSAMTYP=READONLY
VIRQLK9I INITIALISATION FOR SPVIRE01 (SPVIRE01), VERSION 4.58
. . .
VIRB17AI LINE SPVIRE01 (SPVIRE01), RESTARTED TO ALLOW CONNECTION TO SPVIRE01
VIRQLK9I INITIALISATION FOR SPVIRE01 (SPVIRE01), VERSION 4.58
VIRT907I SPVIRE01 SOCKET 00000000 CALLING 192.168.170.081:41031
VIRQLK8I LOCAL LINE SPVIRE01 (SPVIRE01) IS CONNECTED TO REMOTE VIRTEL : SPVIRE01
SPTHOLT1 Connecting to the ‘WRITER’ task SPTHOLT9 and the other ‘READER’ tasks SPTHOLT0
VIRQLK8I LOCAL LINE SPVIRE00 (SPVIRE00) IS CONNECTED TO REMOTE VIRTEL : SPVIRE00
VIRT903W LINE SPVIRE01 HAS A SESSION STARTED WITH TCP/IP TCPIP HIGHEST SOCKET
VIRQLK9I INITIALISATION FOR SPVIRE01 (SPVIRE01), VERSION 4.58
VIRT905I SPVIRE01 SOCKET 00000000 LISTENING 192.168.170.081:41031
VIRT903W LINE SPVIRE99 HAS A SESSION STARTED WITH TCP/IP TCPIP HIGHEST SOCKET
VIRQLK9I INITIALISATION FOR SPVIRE99 (SPVIRE99), VERSION 4.58
VIRT907I SPVIRE99 SOCKET 00000000 CALLING 192.168.170.081:41099
VIRQLK8I LOCAL LINE SPVIRE99 (SPVIRE99) IS CONNECTED TO REMOTE VIRTEL : SPVIRE99
VIRT903W LINE HTTP-VPX HAS A SESSION STARTED WITH TCP/IP TCPIP HIGHEST SOCKET
Once the three tasks have initiated you should see no more “CONNECT” error messages. You can test that
the tree tasks are communicating by doing a “Line” display:-
F SPTHOLT0,LINES
VIR0200I LINES
VIR0201I VIRTEL 4.58 APPLID=SPVIRE00 LINES
VIR0202I INT.NAME EXT.NAME TYPE ACB OR IP
VIR0202I -------- -------- ----- ---------
VIR0202I W-HTTP *GATE
VIR0202I C-HTTP *GATE
VIR0202I SPVIRE00 SPVIRE00 TCP1 192.168.170.81:41030
VIR0202I SPVIRE01 SPVIRE01 TCP1 192.168.170.81:41031
VIR0202I SPVIRE99 SPVIRE99 TCP1 192.168.170.81:41099
VIR0202I V-HTTP HTTP-VPX TCP1 192.168.170.15:41902
VIR0202I ---END OF LIST---
204 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
F SPTHOLT1,LINES
VIR0200I LINES
VIR0201I VIRTEL 4.58 APPLID=SPVIRE01 LINES
VIR0202I INT.NAME EXT.NAME TYPE ACB OR IP
VIR0202I -------- -------- ----- ---------
VIR0202I W-HTTP *GATE
VIR0202I C-HTTP *GATE
VIR0202I SPVIRE00 SPVIRE00 TCP1 192.168.170.81:41030
VIR0202I SPVIRE01 SPVIRE01 TCP1 192.168.170.81:41031
VIR0202I SPVIRE99 SPVIRE99 TCP1 192.168.170.81:41099
VIR0202I V-HTTP HTTP-VPX TCP1 192.168.170.15:41902
VIR0202I ---END OF LIST---
F SPTHOLT9,LINES
VIR0200I LINES
VIR0201I VIRTEL 4.58 APPLID=SPVIRE99 LINES
VIR0202I ALLOCATED IP ADDRESS =192.168.170.39
VIR0202I INT.NAME EXT.NAME TYPE ACB OR IP
VIR0202I -------- -------- ----- ---------
VIR0202I C-HTTP *GATE
VIR0202I V-HTTP *GATE
VIR0202I SPVIRE00 SPVIRE00 TCP1 192.168.170.81:41030
VIR0202I SPVIRE01 SPVIRE01 TCP1 192.168.170.81:41031
VIR0202I SPVIRE99 SPVIRE99 TCP1 192.168.170.81:41099
VIR0202I W-HTTP HTTP-W2H TCP1 :41001
VIR0202I ---END OF LIST---
If the displays match those above then the VIRPLEX has initialized successfully.
Validating the Virplex
Logon to Virtel using the common URL 192.168.170.15:41902. You should be presented with the Applist
screen showing the two 3270 applications dened in the common ARBO.
14.3. ARBO denitions 205
Virtel Connectivity Guide, Release 4.58
The top right hand corner will identify the ‘READER’ instance support this session. In this example this is
Virtel instance SPTHOLT1 (SPVIRE01)
On a separate machine, one with a dierent IP address, logon again to Virtel using the same URL. This
time, if the Sysplex Distributor is working in a “round robin” fashion, it will allocate a dierent ‘READER’
instance. Here is the sample of a second browser session, this time using Chrome, allocating a Virtel session
on Virtel instance SPTHOLT0 (SPVIRE00).
206 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
At this point validation of the Virplex is conrmed.
Testing QLNK communication.
To test that the Virtels are communicating, maintenance will be uploaded via the ‘WRITER’ task. The
‘WRITER’ task will distributed this to the two ‘READER’ tasks. Connect to the TSO application to
determine the current maintenance level.
Is shows as UPDT level V4.58 / 5687. Conrm this with the Administration Portal on the ‘WRITER’ task
by accessing the ‘Admin Portal’ through the ‘WRITER’ URL 192.168.170.39:41001. The maintenance level
is shown in the Middle of the Tool Bar area on the screen:-
This conrms that both the ‘WRITER’ and ‘READER’ instances had loaded the SAMP TRSF le. Using the
“Drag and Drop” feature upload some maintenance to the W2H-DIR le. In this example the maintenance
level TP 5695 is uploaded via the ‘WRITER’ instance SPTHOLT9(SPVIRE99). A refresh of the browser
(CTRL+UP+DEL + CTRL+R) now shows the maintenance level to be 4.58 (5695):-
14.3. ARBO denitions 207
Virtel Connectivity Guide, Release 4.58
If a new browser window is opened on another machine, and TSO is accessed through the common URL /
APPLIST navigation, the maintenance level has changed to V4.58 UPDT 5695:-
This conrms that the ‘WRITER’ and ‘READER’ tasks are communicating and the automatic distribution
of maintenance out to ‘READER’ task environments is working. The following traces on the ‘WRITER’
task show that the ‘WRITER is communicating with ‘READER’ tasks:-
Diagnosing Virplex issues
1. Issue a trace command on the writer task to trace all QLNK lines. In this example
,→the following commands would be issued:-
F SPTHOLT9,TRACE,L=SPVIRE00
F SPTHOLT9,TRACE,L=SPVIRE01
F SPTHOLT9,TRACE,L=SPVIRE99
2. Perform some Virplex activing – upload some maintenance for example.
3. Issue a line display for each Virplex instance.
F SPTHOLTx,LINES
4. Take a Virtel SNAP of the ‘Writer’ task.
208 Chapter 14. VIRPLEX
Virtel Connectivity Guide, Release 4.58
F SPTHOLT9,SNAP
5. Obtain the Virtel logs from the ‘Writer’ task and the one of the ‘READER’ tasks.
Open a problem with your local Syspertec Support Engineer and send them the output
,→plus a description of the problem you experienced.
14.3. ARBO denitions 209
Virtel Connectivity Guide, Release 4.58
210 Chapter 14. VIRPLEX
CHAPTER
FIFTEEN
PROTECTING BUSINESS ASSETS WITH VIRTEL RULES
15.1 Introduction
In this chapter we discuss how to protect access to business assets using Virtel rules. In this scenario with
have two types of business assets or applications. The rst type is the production assets which are protected
by LDAP and use SSO to facilitate security and automatic logon without the user having to specify a userid
and password. The other type of business asset is a standard application, like TSO or CICS, which requires
the user to enter a userid and password when the application is accessed. LDAP and SSO are not discussed in
this newsletter. There may be alternatives to this SSO setup but for our scenario we are assuming two types
of asset – secure (requiring no application logon) and insecure (application logon required). The scenario
utilizes a proxy server to load balance across the Virtel instances.
211
Virtel Connectivity Guide, Release 4.58
212 Chapter 15. Protecting business assets with Virtel Rules
Virtel Connectivity Guide, Release 4.58
15.2 Virtel Setup
From a Virtel perspective it has been decided that secure assets are associated with port 41002, and non-
secure through port 41003. Access to the assets should only be through the proxy server using a secure port,
in our case the standard SSL port 443. Our goal is to protect the assets from being accessed internal, or
external, using the assigned Virtel IP and port addresses. For example, users in the accounts department
should be able to access PROD IMS/CICS. Other users, who work osite or from home, and have access to
the company VPN shouldn’t be able to access PROD IMS/CICS. In this simplistic scenario, anyone could in
theory could access any one of the Virtel instances through their internal IP address – 192.168.07x.10x:4100x
and attempt to logon. What is required is means to guarantee that access to any of the assets should only
be via the proxy server and not through any other IP address.
15.2.1 Virtel Rules
Using Virtel Rules we can compare the calling IP address and if it doesn’t match with the rule then the user
will be re-directed to another Virtel entry point. To implement this protection we use the following ARBO
statements for each line, 41002 and 41003:-
RULE ID=R0000100,
RULESET=C-HTTP, <Our Line 41002
STATUS=ACTIVE,
DESC='HTTP access (Test calling address)',
ENTRY=EPSEC, <Associated Entry point
IPADDR=(EQUAL,192.168.092.160), <IP address of Proxy
NETMASK=255.255.255.255
*
RULE ID=R0000199,
RULESET=C-HTTP, <Our Line 41002
STATUS=ACTIVE,
DESC='HTTP access (Calling IP address not valid)',
ENTRY=EPREJECT
*
RULE ID=R0000200,
RULESET=R-HTTP, <Our Line 41003
STATUS=ACTIVE,
DESC='HTTP access (Test calling address)',
ENTRY=EPSEC, <Associated Entry point
IPADDR=(EQUAL,192.168.092.160), <IP address of Proxy
NETMASK=255.255.255.255
*
RULE ID=R0000299,
RULESET=R-HTTP, <Our Line 41003
STATUS=ACTIVE,
DESC='HTTP access (Calling IP address not valid)',
ENTRY=EPREJECT
ENTRY ID=EPREJECT,
DESC='Entry point for unauthorized HTTP users',
TRANSACT=REJ,
TIMEOUT=0720,
ACTION=0,
EMUL=HTML,
SIGNON=VIR0020H,
MENU=VIR0021A,
EXTCOLOR=X
*
TRANSACT ID=REJ-00,
15.2. Virtel Setup 213
Virtel Connectivity Guide, Release 4.58
NAME=EPREJECT,
DESC="Default directory = entry point name",
APPL=CLI-DIR, <User template directory
TYPE=4,
TERMINAL=CLLOC,
STARTUP=2,
SECURITY=0
So what is happening here? When a user attempts to establish a session Virtel will match the users calling
IP address against the IPADDR in rule R0000x00. If it matches then they will be able to access the entry
point dened in the rule – in this case EPSEC or EPNSEC. For line 41002 this Entry Point will contain a
list of the W2H applications using SSO. For line 41003, using Entry Point EPNSEC, this will contain a list
of W2H transactions which use standard RACF protection.
Now, if the calling IP addressed is not matched, the RULE fails and the next rule in the ruleset is tested,
in this case rule R0000x99. This is a catch all rule. Any user falling into this rule will be directed to entry
point EPREJECT. The Entry Point EPREJECT only has one transaction, its default transaction, and this
will invoke the template page EPREJECT.HTM.
To protect the business assets the calling IP address can only be that of the proxy server - 192.168.092.160.
Any other calling IP address will be rejected by the Virtel ruleset. By default, the ruleset associated with a
line is normally the internal name of the line – C-HTTP for example. How the rejected session is handled
depends on how Virtel has been setup.
15.2.2 Default Rule Template
In the following example, the default template EPREJECT.HTM, which is associated with the entry point
EPREJECT, looks like this:-
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<!--VIRTEL start="{{{" end="}}}" -->
<html>
<script>
// customization for reject
window.location.replace("http://www.mycompany.com");
</script>
</html>
This template must exist in the CLI-DIR directory as this is where the Entry Point EPREJECT expects to
nd them. When the template is served it will display the companies “public” web site.
To upload the ARBO statements to your ARBO use the following JCL:-
//*
// SET LOAD=SPTHOLT.VIRT456.LOADLIB
// SET ARBO=SP000.SPVIREH0.ARBO1A
//*
//DELETE EXEC PGM=VIRCONF,PARM='LOAD,NOREPL',REGION=2M
//STEPLIB DD DSN=&LOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//VIRARBO DD DSN=&ARBO,DISP=SHR
//SYSIN DD *
DELETE TYPE=RULE,ID=R0000100 Delete rule
DELETE TYPE=RULE,ID=R0000199 Delete rule
DELETE TYPE=RULE,ID=R0000200 Delete rule
214 Chapter 15. Protecting business assets with Virtel Rules
Virtel Connectivity Guide, Release 4.58
DELETE TYPE=RULE,ID=R0000299 Delete rule
DELETE TYPE=ENTRY,ID=EPREJECT Entry point
DELETE TYPE=TRANSACT,ID=REJ-00 Delete transaction
*
//CONFIG EXEC PGM=VIRCONF,PARM='LOAD,NOREPL',REGION=2M
//STEPLIB DD DSN=&LOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//VIRARBO DD DSN=&ARBO,DISP=SHR
//SYSIN DD *
RULE Definitions
/*
15.2. Virtel Setup 215
Virtel Connectivity Guide, Release 4.58
216 Chapter 15. Protecting business assets with Virtel Rules
CHAPTER
SIXTEEN
APPENDIX
16.1 Trademarks
SysperTec, the SysperTec logo, syspertec.com and VIRTEL are trademarks or registered trademarks of
SysperTec Communication Group, registered in France and other countries.
IBM, VTAM, CICS, IMS, RACF, DB2, MVS, WebSphere, MQSeries, System z are trademarks or registered
trademarks of International Business Machines Corp., registered in United States and other countries.
Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered trademarks or trademarks
of Adobe Systems Incorporated in the United States and other countries.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all
Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its aliates.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Other company, product, or service names may be trademarks or service names of others.
217
INDEX
Add or changing LU Names
X25 AntiPCNE line, 91
Adding headers to the HTTP request
SSO, Passtickets and Proxy Servers, 169
Administration, 21
Conguration Menu, 22
Screen Navigation, 23
Sub-Application Menu, 23
Arbo denitions
Virplex, 197
AT-TLS Secure Session, 157
Client certicates, 164
Installation, 159
Operations, 161
Problem determination, 162
Resources, 165
The Cipher suites, 164
Batch Line
Lines, 51
Parameters, 51
Terminal Denitions, 52
CICS Denitions
HTTP Inbound Line, 37
HTTP Ôutbound SMTP Line, 42
Native Gateway Line, 55
Client certicates
AT-TLS Secure Session, 164
Common Errors
SSO, Passtickets and Proxy Servers, 181
Comparison table
Controlling LUNAMEs, 157
Conguration Menu
Administration, 22
Connect to CICS and autostart transaction
Scripts Examples, 126
Connect to CICS and navigation of user application
Scripts Examples, 128
Connect to CICS and transmission of credentials
Scripts Examples, 127
Connect to CICS VSE with ICCF signon and start
of CEMT transaction
Scripts Examples, 127
Connect to TSO and start of ISPF
Scripts Examples, 127
Connection / Disconnection Scripts, 121
Method of Operation, 125
Orders, 124
Script Programming Language, 123
System Variables, 123
Transmission and lter commands, 123
Connection Modes, 135
Dynamic Terminal Pools, 139
Logical Terminals, 144
Non-Dynamic Terminal Pools, 140
Physical Terminal Pools, 139
Relay Mode, 137
RELAY Mode Terminal Connection Example,
143
Terminal connection types, 137
Terminal Pool Denition Examples, 140
Terminal Pool Selection, 141
Virtel Terminal Connection Examples, 143
Welcome Mode, 137
WELCOME Mode Terminal Connection Exam-
ple, 143
X25 Asynchronous Terminal Connection Exam-
ple, 143
Controlling LUNAMEs, 145
Comparison table, 157
LU Nailing by cookie, 154
UserData example using a LU Name, 150
UserData example using a work station name,
147
Using an IP address, 155
Using an LU Name with no predened terminal,
151
Debugging and diagnosing
Virplex, 208
Default Rule Template
Protecting business assets with Virtel Rules, 214
Detail Display
Entry Point Management Sub-Application, 109
218
Virtel Connectivity Guide, Release 4.58
External Server Management Sub-Application,
132
Line Management Sub-Application, 27
Terminal Management Sub-Application, 102
Transactions, 116
Virtel Rules, 96
Dynamic Terminal Pools
Connection Modes, 139
Entry Point
IMS Connect, 44
Entry Point Management Sub-Application
Detail Display, 109
Entry Points, 107
Menu Programs, 112
Parameters, 110
Security, 107
Selection an Entry Point, 107
Signon Programs, 112
Transaction list Display, 109
Entry Point Sub-Application
Summary Display, 108
Entry Points, 106
Entry Point Management Sub-Application, 107
Example Rules
Protecting business assets with Virtel Rules, 213
External Server Management Sub-Application
Detail Display, 132
External Servers, 131
Parameters, 133
Security, 131
Summary Display, 131
External Servers, 129
External Server Management Sub-Application,
131
HTTP Inbound Line
CICS Denitions, 37
Lines, 33
Parameters, 33
Terminal Denitions, 34
VTAM Terminal Denitions, 37
HTTP Outbound Line
Parameters, 39
HTTP Outbound line
Lines, 38
HTTP Outbound SMTP Line
Parameters, 40
Terminal Denitions, 41
VTAM Terminal Denitions, 42
HTTP Outbound SMTP line
Lines, 39
HTTP Ôutbound SMTP Line
CICS Denitions, 42
IMS Connect
Entry Point, 44
Terminal Denitions, 43
Transactions, 45
IMS Connect Line
Lines, 43
Installation
AT-TLS Secure Session, 159
Installation Overview
Virplex, 203
JCL Examples
Virplex, 201
Line Management Sub-Application
Detail Display, 27
Lines, 25
Parameters, 27
Summary Display, 25
Line Overview Sub-Application
Lines, 32
Line terminals
Native Gateway Line, 54
Lines, 24
Batch Line, 51
HTTP Inbound Line, 33
HTTP Outbound line, 38
HTTP Outbound SMTP line, 39
IMS Connect Line, 43
Line Management Sub-Application, 25
Line Overview Sub-Application, 32
MQ Line, 48
Native TCP/IP Gateway line, 53
VIRPASS TCP line (VIRKIX), 57
VIRPASS TCP line (VIRNT), 59
VIRPASS XM line (VIRKIX), 62
X25 Anti Fast Connect (FastC) line, 84
X25 AntiGATE line, 81
X25 AntiPCNE line, 86
X25 GATE Fast-Connect (FC) line, 77
X25 GATE Non Fast-Connect (NFC) line, 72
X25 VIRNEOX line, 70
X25 VIRPESIT line, 68
X25 XOT line, 65
Load balancing with a Distributed VIPA
Running multiple instances of Virtel, 191
Load balancing with Apache Proxy
Running multiple instances of Virtel, 192
Logical Terminals
Connection Modes, 144
LU Nailing by cookie
Controlling LUNAMEs, 154
Menu Programs
Entry Point Management Sub-Application, 112
Index 219
Virtel Connectivity Guide, Release 4.58
Message Format
Native Gateway Line, 56
Message format
ÎMS Connect, 47
Method of Operation
Connection / Disconnection Scripts, 125
MQ Line
Lines, 48
MQ Line parameters, 48
Terminals Parameters, 49
MQ Line parameters
MQ Line, 48
Native Gateway Line
CICS Denitions, 55
Line terminals, 54
Message Format, 56
Native TCP/IP Gateway line parameters, 53
Relay Pool, 54
Terminal Parameters, 54
VTAM Terminal Denitions, 55
Native TCP/IP Gateway line
Lines, 53
Native TCP/IP Gateway line parameters
Native Gateway Line, 53
Navigation
Terminal Management Sub-Application, 102
NCP Parameters
X25 GATE NFC line, 74
NCP/NPSI Denitions
X25 GATE FastC line, 78
NCP/NPSI denitions for X25 Non Gate terminals
X25 AntiPCNE line, 92
Non-Dynamic Terminal Pools
Connection Modes, 140
NPSI Parameters
X25 GATE NFC line, 74
Operations
AT-TLS Secure Session, 161
Orders
Connection / Disconnection Scripts, 124
Parameters
Batch Line, 51
Entry Point Management Sub-Application, 110
External Server Management Sub-Application,
133
HTTP Inbound Line, 33
HTTP Outbound Line, 39
HTTP Outbound SMTP Line, 40
Line Management Sub-Application, 27
Terminal Management Sub-Application, 103
Transactions, 117
VIRPASS (VIRKIX) line, 57
VIRPASS (VIRNT) line, 59
VIRPASS XM Line (VIRKIX), 62
Virtel Rules, 97
X25 Anti-FastC line, 84
X25 AntiGATE line, 81
X25 AntiPCNE line, 86
X25 GATE FastC line, 77
X25 GATE NFC line, 72
X25 VIRNEOX line, 70
X25 VIRPESIT line, 68
X25 XOT line, 65
Pattern Characters
Terminal Management Sub-Application, 104
Physical Terminal Pools
Connection Modes, 139
Problem determination
AT-TLS Secure Session, 162
Protecting business assets with Virtel Rules, 209
Default Rule Template, 214
Example Rules, 213
Virtel Setup, 213
QLNK communications
Virplex, 207
RACF Passtickets
SSO, Passtickets and Proxy Servers, 171
Related material
SSO, Passtickets and Proxy Servers, 182
Relay Mode
Connection Modes, 137
RELAY Mode Terminal Connection Example
Connection Modes, 143
Relay Pool
Native Gateway Line, 54
Resources
AT-TLS Secure Session, 165
Routing Incoming Calls
X25 GATE NFC line, 75
Running multiple instances of Virtel, 182
Load balancing with a Distributed VIPA, 191
Load balancing with Apache Proxy, 192
Session Anity with Apache, 192
Session Anity with DVIPA, 191
SYSPLEX denitions, 184
Virtel TCT Settings, 184
Workload balancing, 186
Scenarios
ÎMS Connect, 46
Screen Navigation
Administration, 23
Script Programming Language
Connection / Disconnection Scripts, 123
Scripts Examples, 126
220 Index
Virtel Connectivity Guide, Release 4.58
Connect to CICS and autostart transaction, 126
Connect to CICS and navigation of user appli-
cation, 128
Connect to CICS and transmission of creden-
tials, 127
Connect to CICS VSE with ICCF signon and
start of CEMT transaction, 127
Connect to TSO and start of ISPF, 127
Service Transactions, 128
Security
Entry Point Management Sub-Application, 107
External Server Management Sub-Application,
131
Terminal Sub-Application, 101
Selection an Entry Point
Entry Point Management Sub-Application, 107
Service Transactions
Scripts Examples, 128
Session Anity with Apache
Running multiple instances of Virtel, 192
Session Anity with DVIPA
Running multiple instances of Virtel, 191
Sharing of FastC Lines
X25 GATE FastC line, 79
Signon Programs
Entry Point Management Sub-Application, 112
SSO, Passtickets and Proxy Servers, 165
Adding headers to the HTTP request, 169
Common Errors, 181
RACF Passtickets, 171
Related material, 182
Virtel Requirements, 175
Sub-Application Menu
Administration, 23
Summary Display
Entry Point Sub-Application, 108
External Server Management Sub-Application,
131
Line Management Sub-Application, 25
Terminal Management Sub-Application, 101
Transactions, 115
Virtel Rules, 95
Support of non GATE terminals
X25 AntiPCNE line, 92
SYSPLEX denitions
Running multiple instances of Virtel, 184
System Variables
Connection / Disconnection Scripts, 123
TCPIP denitions
Virplex, 202
TCT denitions
Virplex, 196
Terminal connection types
Connection Modes, 137
Terminal Denitions
Batch Line, 52
HTTP Inbound Line, 34
HTTP Outbound SMTP Line, 41
IMS Connect, 43
VIRPASS (VIRKIX) line, 57
VIRPASS (VIRNT) line, 60
VIRPASS XM Line (VIRKIX), 62
X25 Anti-FastC line, 84
X25 AntiGATE line, 81
X25 AntiPCNE line, 86
X25 GATE FastC line, 78
X25 GATE NFC line, 73
X25 VIRNEOX line, 71
X25 VIRPESIT line, 69
X25 XOT line, 66
Terminal Management Sub-Application
Detail Display, 102
Navigation, 102
Parameters, 103
Pattern Characters, 104
Summary Display, 101
Terminals, 101
Terminal Parameters
Native Gateway Line, 54
Terminal Pool Denition Examples
Connection Modes, 140
Terminal Pool Selection
Connection Modes, 141
Terminal Sub-Application
Security, 101
Terminals, 99
Terminal Management Sub-Application, 101
Terminals Parameters
MQ Line, 49
The Cipher suites
AT-TLS Secure Session, 164
Transaction list Display
Entry Point Management Sub-Application, 109
Transactions, 113
Detail Display, 116
IMS Connect, 45
Parameters, 117
Summary Display, 115
Transmission and lter commands
Connection / Disconnection Scripts, 123
UserData example using a LU Name
Controlling LUNAMEs, 150
UserData example using a work station name
Controlling LUNAMEs, 147
Using an IP address
Controlling LUNAMEs, 155
Index 221
Virtel Connectivity Guide, Release 4.58
Using an LU Name with no predened terminal
Controlling LUNAMEs, 151
Validation
Virplex, 205
VIRPASS (VIRKIX) line
Parameters, 57
Terminal Denitions, 57
VIRPASS (VIRNT) line
Parameters, 59
Terminal Denitions, 60
VIRPASS TCP line (VIRKIX)
Lines, 57
VIRPASS TCP line (VIRNT)
Lines, 59
VIRPASS XM Line (VIRKIX)
Parameters, 62
Terminal Denitions, 62
VIRPASS XM line (VIRKIX)
Lines, 62
VIRPLEX, 193
Virplex
Arbo denitions, 197
Debugging and diagnosing, 208
Installation Overview, 203
JCL Examples, 201
QLNK communications, 207
TCPIP denitions, 202
TCT denitions, 196
Validation, 205
VTAM denitions, 202
Virtel Requirements
SSO, Passtickets and Proxy Servers, 175
Virtel Rules, 93
Detail Display, 96
Parameters, 97
Summary Display, 95
Virtel Setup
Protecting business assets with Virtel Rules, 213
Virtel TCT Settings
Running multiple instances of Virtel, 184
Virtel Terminal Connection Examples
Connection Modes, 143
VTAM denitions
Virplex, 202
VTAM Terminal Denitions
HTTP Inbound Line, 37
HTTP Outbound SMTP Line, 42
Native Gateway Line, 55
X25 Anti-FastC line, 85
X25 AntiPCNE line, 91
X25 GATE FastC line, 78
X25 GATE NFC line, 73
X25 XOT line, 67
VTAM Terminal Denitions for X25 Non Gate ter-
minals.
X25 AntiPCNE line, 92
VTAM Terminals Denitions
X25 AntiGATE line, 82
Welcome Mode
Connection Modes, 137
WELCOME Mode Terminal Connection Example
Connection Modes, 143
Workload balancing
Running multiple instances of Virtel, 186
X25 Anti Fast Connect (FastC) line
Lines, 84
X25 Anti-FastC line
Parameters, 84
Terminal Denitions, 84
VTAM Terminal Denitions, 85
X25 AntiGATE line
Lines, 81
Parameters, 81
Terminal Denitions, 81
VTAM Terminals Denitions, 82
X25 AntiPCNE line
Add or changing LU Names, 91
Lines, 86
NCP/NPSI denitions for X25 Non Gate termi-
nals, 92
Parameters, 86
Support of non GATE terminals, 92
Terminal Denitions, 86
VTAM Terminal Denitions, 91
VTAM Terminal Denitions for X25 Non Gate
terminals., 92
X25 Asynchronous Terminal Connection Example
Connection Modes, 143
X25 GATE Fast-Connect (FC) line
Lines, 77
X25 GATE FastC line
NCP/NPSI Denitions, 78
Parameters, 77
Sharing of FastC Lines, 79
Terminal Denitions, 78
VTAM Terminal Denitions, 78
X25 GATE NFC line
NCP Parameters, 74
NPSI Parameters, 74
Parameters, 72
Routing Incoming Calls, 75
Terminal Denitions, 73
VTAM Terminal Denitions, 73
X25 GATE Non Fast-Connect (NFC) line
Lines, 72
222 Index
Virtel Connectivity Guide, Release 4.58
X25 VIRNEOX line
Lines, 70
Parameters, 70
Terminal Denitions, 71
X25 VIRPESIT line
Lines, 68
Parameters, 68
Terminal Denitions, 69
X25 XOT line
Lines, 65
Parameters, 65
Terminal Denitions, 66
VTAM Terminal Denitions, 67
ÎMS Connect
Message format, 47
Scenarios, 46
Index 223

Navigation menu