Virtel User Guide
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 321
| Download | |
| Open PDF In Browser | View PDF |
Virtel User Guide
Release 4.57
Syspertec Communications
Feb 08, 2018
TABLE OF CONTENTS:
1 The Virtel Engine
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.1 What is Virtel . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2 VIRTEL Web Access (VWA) . . . . . . . . . . . . . . .
1.1.3 VIRTEL Web Modernisation (VWM) . . . . . . . . . . .
1.1.4 VIRTEL Web Integration (VWI) . . . . . . . . . . . . .
1.1.5 VIRTEL Service Transactions . . . . . . . . . . . . . . .
1.2 VIRTEL URL Formats . . . . . . . . . . . . . . . . . . . . . . .
1.2.1 Static pages . . . . . . . . . . . . . . . . . . . . . . . . .
1.2.2 How the path name corresponds to a VIRTEL directory
1.2.3 Dynamic pages . . . . . . . . . . . . . . . . . . . . . . .
1.2.4 3270 session management . . . . . . . . . . . . . . . . .
1.2.5 Capability URLs . . . . . . . . . . . . . . . . . . . . . .
1.2.6 Transmission of Security Tokens by URL . . . . . . . . .
1.2.7 Propagation of signon by URL . . . . . . . . . . . . . .
1.2.8 The Universal Transaction . . . . . . . . . . . . . . . . .
1.3 Directory Management . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 Accessing the administration application . . . . . . . . .
1.3.2 Access through 3270 . . . . . . . . . . . . . . . . . . . .
1.3.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.4 Creating, modifying, and deleting directories . . . . . . .
1.3.5 Defining directory parameters . . . . . . . . . . . . . . .
1.3.6 Associated functions . . . . . . . . . . . . . . . . . . . .
1.3.7 Acccess administration portal via the web . . . . . . . .
1.4 Creating Virtel Template Pages . . . . . . . . . . . . . . . . . .
1.4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2 Defining the tag delimiters . . . . . . . . . . . . . . . . .
1.4.3 Session and context management . . . . . . . . . . . . .
1.4.4 Transmitting data to the host . . . . . . . . . . . . . . .
1.4.5 Where to position the elements of an HTML page . . . .
1.4.6 Inserting host application data into a page . . . . . . . .
1.4.7 Colour and font management . . . . . . . . . . . . . . .
1.4.8 Cursor management . . . . . . . . . . . . . . . . . . . .
1.4.9 Function key management . . . . . . . . . . . . . . . . .
1.4.10 Setting and unsetting local options . . . . . . . . . . . .
1.4.11 Handling table variables . . . . . . . . . . . . . . . . . .
1.4.12 Inserting VIRTEL configuration values into a template .
1.4.13 Conditional generation . . . . . . . . . . . . . . . . . . .
1.4.14 Debugging facilities . . . . . . . . . . . . . . . . . . . . .
1.4.15 Signon and password management . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
3
5
8
11
12
13
13
14
19
21
23
23
24
24
25
25
25
26
26
28
29
30
33
33
33
34
35
35
36
42
45
47
49
50
54
56
58
58
i
1.4.16 Encryption management . . . . . . . . . . . . . . .
1.4.17 EBCDIC translation management . . . . . . . . . .
1.4.18 HTTP protocol management . . . . . . . . . . . .
1.4.19 Cache management . . . . . . . . . . . . . . . . . .
1.4.20 MIME type management . . . . . . . . . . . . . . .
1.4.21 Capability tokens . . . . . . . . . . . . . . . . . . .
1.4.22 Template Page upload . . . . . . . . . . . . . . . .
1.4.23 3287 printing . . . . . . . . . . . . . . . . . . . . .
1.4.24 Generating PDF output . . . . . . . . . . . . . . .
1.5 Web Access Customization . . . . . . . . . . . . . . . . . .
1.5.1 Uploading HTML Pages . . . . . . . . . . . . . . .
1.5.2 Web Access Settings . . . . . . . . . . . . . . . . .
1.6 Application Selection Menu . . . . . . . . . . . . . . . . . .
1.6.1 Contents of menu . . . . . . . . . . . . . . . . . . .
1.6.2 Presentation modes . . . . . . . . . . . . . . . . . .
1.7 Printing With Web Access . . . . . . . . . . . . . . . . . .
1.7.1 VIRTEL definitions for virtual printers . . . . . . .
1.7.2 Associating virtual printers with terminals . . . . .
1.7.3 Autoconnect for virtual printers . . . . . . . . . . .
1.7.4 VTAM definitions for virtual printers . . . . . . . .
1.7.5 CICS definitions for virtual printers . . . . . . . . .
1.7.6 Scenarios for SCS printing . . . . . . . . . . . . . .
1.7.7 SCS to PDF conversion . . . . . . . . . . . . . . .
1.7.8 PCL printing . . . . . . . . . . . . . . . . . . . . .
1.7.9 PCL to PDF conversion . . . . . . . . . . . . . . .
1.8 TSO File Transfer . . . . . . . . . . . . . . . . . . . . . . .
1.8.1 Definitions required for file transfer . . . . . . . . .
1.8.2 Toolbar icons for file transfer . . . . . . . . . . . .
1.8.3 Receiving a file . . . . . . . . . . . . . . . . . . . .
1.8.4 Sending a file . . . . . . . . . . . . . . . . . . . . .
1.8.5 Selecting PC Codepage for file transfer . . . . . . .
1.8.6 Saving and reusing file transfer parameters . . . . .
1.9 Accessing VTAM Applications . . . . . . . . . . . . . . . .
1.9.1 VTAM logon screen . . . . . . . . . . . . . . . . . .
1.9.2 Installing the VTAM logon transaction . . . . . . .
1.10 Site Customization - Colors And Logo . . . . . . . . . . . .
1.10.1 Using a CSS file for customization . . . . . . . . .
1.10.2 Customizing the toolbar color by application . . .
1.10.3 Adding custom text to the toolbar . . . . . . . . .
1.10.4 Showing / Hiding server informations . . . . . . . .
1.10.5 Hiding the toolbar . . . . . . . . . . . . . . . . . .
1.10.6 Adding a company logo . . . . . . . . . . . . . . .
1.10.7 Removing 3D/hover effects on the toolbar buttons
1.10.8 Changing background color of the toolbar buttons
1.10.9 Icon display troubleshooting . . . . . . . . . . . . .
1.11 Site Customization - Javascript Functions . . . . . . . . . .
1.11.1 Javascript Exits which can be customized . . . . .
1.11.2 Customizing Toolbar icons . . . . . . . . . . . . . .
1.11.3 Centering non-standard icons . . . . . . . . . . . .
1.11.4 Removing unwanted toolbar icons . . . . . . . . . .
1.11.5 Positioning Toolbar Icons . . . . . . . . . . . . . .
1.11.6 Modifying the text of the status bar . . . . . . . .
1.11.7 Custom hotspot recognition . . . . . . . . . . . . .
1.11.8 Adding a watermark to the 3270 screen . . . . . . .
ii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
60
61
63
64
64
65
66
67
68
70
70
70
80
80
81
84
84
85
86
87
87
88
88
88
88
90
90
90
91
94
98
98
100
100
101
102
102
103
103
104
105
106
106
107
107
108
108
109
110
110
111
112
113
113
1.11.9 Modifying Web Access Settings . . . . . . . . . . . . . . . . . . . .
1.12 Site Customization - The Help Page . . . . . . . . . . . . . . . . . . . . . .
1.12.1 Standard Help Page . . . . . . . . . . . . . . . . . . . . . . . . . .
1.12.2 Installing a Custom Help Page . . . . . . . . . . . . . . . . . . . .
1.13 Enable Copy, Cut And Paste . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.1 Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.2 Firefox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.3 Chrome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.4 Manage the settings on Host with chrome . . . . . . . . . . . . . .
1.13.5 Using Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.6 Edge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14 Virtel Customization Modes . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.1 Compatibility Mode . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.2 Option mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.3 Default mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.14.4 Global level modifications (All transactions under an Entry Point)
1.14.5 Transaction level modifications (Individual transactions) . . . . . .
1.14.6 Compatibility Option id . . . . . . . . . . . . . . . . . . . . . . . .
1.14.7 Defining Transaction Options . . . . . . . . . . . . . . . . . . . . .
1.15 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.1 Storing the Macros . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.2 Macros in Local Storage . . . . . . . . . . . . . . . . . . . . . . . .
1.15.3 Macro controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.15.4 Macros in VIRTEL Storage . . . . . . . . . . . . . . . . . . . . . .
1.15.5 Setting up to use DDI and macros . . . . . . . . . . . . . . . . . .
1.15.6 User Macros synchronization . . . . . . . . . . . . . . . . . . . . .
1.15.7 Managing macros with DDI . . . . . . . . . . . . . . . . . . . . . .
1.15.8 Automatic refresh of macros in local storage . . . . . . . . . . . . .
1.15.9 Format of the macros.json file . . . . . . . . . . . . . . . . . . . . .
1.15.10 Available macro commands . . . . . . . . . . . . . . . . . . . . . .
1.15.11 DDI Macro Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16 VIRTEL Web Modernisation . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16.1 VIRTEL Presentation modules and Scenarios . . . . . . . . . . . .
1.16.2 Scenarios stored in a load library . . . . . . . . . . . . . . . . . . .
1.16.3 Scenarios stored in a VSAM directory . . . . . . . . . . . . . . . .
1.16.4 Using a presentation module . . . . . . . . . . . . . . . . . . . . . .
1.16.5 Types of scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.16.6 Virtel Scenario language . . . . . . . . . . . . . . . . . . . . . . . .
1.16.7 Examples of VIRTEL Web Modernisation Scenarios . . . . . . . .
1.16.8 Scenario AUTOREFRESH . . . . . . . . . . . . . . . . . . . . . . .
1.16.9 PDF output generation . . . . . . . . . . . . . . . . . . . . . . . . .
1.17 VIRTEL Web Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.17.1 Parsing Query input . . . . . . . . . . . . . . . . . . . . . . . . . .
1.17.2 Parsing XML input . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.17.3 Presentation of XML output . . . . . . . . . . . . . . . . . . . . . .
1.17.4 VIRTEL as an XML parser/generator . . . . . . . . . . . . . . . .
1.17.5 Automatic scenario generation . . . . . . . . . . . . . . . . . . . . .
1.18 Incoming E-mails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.18.1 Rules of the SMTP line . . . . . . . . . . . . . . . . . . . . . . . .
1.18.2 File transfer by e-mail . . . . . . . . . . . . . . . . . . . . . . . . .
1.18.3 Starting an application by E-Mail . . . . . . . . . . . . . . . . . . .
1.19 VIRTEL Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.19.1 Assembling the VIRTCT for VIRTEL Batch . . . . . . . . . . . . .
1.19.2 Allocating the page template file for VIRTEL Batch . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
114
115
115
116
118
118
118
122
125
127
129
130
130
131
131
131
133
134
134
139
139
140
141
143
143
146
146
153
153
153
154
155
155
155
155
156
156
158
210
215
216
219
219
221
226
228
232
235
235
235
236
239
239
241
iii
1.19.3
1.19.4
1.19.5
1.19.6
1.19.7
Allocating work files for VIRTEL Batch
Running the VIRTEL Batch job . . . . .
VIRTEL Batch commands . . . . . . . .
VIRTEL Batch RAW command . . . . .
VIRTEL Batch return codes . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
241
242
243
244
245
2 Outgoing Calls
247
2.1 Outgoing E-mails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
3 Programming Interfaces
3.1 Structred Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 General format of a 3270 structured field . . . . . . . . . . . . . . .
3.1.2 Sending structured fields via the Write Structured Field command
3.1.3 Sending structured fields using the SRTVIRTEL prefix . . . . . . .
3.1.4 How To Determine If Running Under Virtel . . . . . . . . . . . . .
3.1.5 Use a different transaction code . . . . . . . . . . . . . . . . . . . .
3.1.6 Include parameters after the transaction code . . . . . . . . . . . .
3.1.7 Use a specific range of terminal names . . . . . . . . . . . . . . . .
3.1.8 FA88: Transmit large data message to application . . . . . . . . . .
3.1.9 FAC8: Selection of page template . . . . . . . . . . . . . . . . . . .
3.1.10 FAE5, FAE6: Sending a table variable . . . . . . . . . . . . . . . .
3.1.11 Call Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.12 HOST4WEB commands . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
249
249
249
250
250
250
250
251
252
253
254
256
257
265
4 Incoming Calls
269
4.1 Incoming E-mails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
4.1.1 FAC8: Retrieve data from an e-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
4.1.2 FAD4: Sending an e-mail from a host application . . . . . . . . . . . . . . . . . . . . 272
5 Security
5.1 VIRTEL Web Access Security . . . . . . . .
5.1.1 Specifying security in the entry point
5.1.2 Specifying security in the transaction
5.1.3 Mixed-case password support . . . .
5.1.4 Automatic retrieval of username . . .
5.1.5 Data encryption by AT-TLS/SSL . .
5.1.6 Identification by certificate . . . . . .
5.1.7 Password encryption . . . . . . . . .
5.1.8 Signon using HTML fields . . . . . .
5.1.9 Virtel Rules . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
275
275
275
276
276
276
277
277
278
278
279
6 HOWTOs
6.1 How To Use Different Screen Sizes . . . . . . . . . . . . .
6.1.1 LOGMODE defined by the transaction . . . . . .
6.1.2 Assigning a LOGMODE by URL parameter . . .
6.1.3 User-specified LOGMODE . . . . . . . . . . . . .
6.1.4 Dynamic logmode with user-specified screen size
6.2 How To Support Multiple Codes Pages . . . . . . . . . .
6.2.1 Defining Code Pages translation defaults . . . . .
6.2.2 Supporting multiple countries. . . . . . . . . . . .
6.3 How To Handle Host Session Termination . . . . . . . . .
6.3.1 Return to the application selection menu . . . . .
6.3.2 Displaying a specific page on disconnection . . .
6.3.3 Closing the browser window automatically . . . .
6.4 How To Access A Host Application Directly . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
283
283
283
284
285
286
286
286
287
287
287
287
288
288
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6.4.1 Full path URL . . . . . . . . . . . .
6.4.2 Default URL for the entry point . . .
6.5 How To Change The Font For Web Access .
6.6 How To Change The 3270 Display Style . . .
6.7 How To Customize The Enter Key Settings .
6.7.1 Managing CTRL keydown being lost
6.8 How To Customize Display Styles . . . . . .
6.8.1 Add or remove a display style . . . .
6.8.2 Add or remove a print style . . . . .
6.8.3 3270 support blinking fields . . . . .
6.9 How To Change The Default User Settings .
6.10 How To Support A Reverse Proxy . . . . . .
6.11 How To Support Virtual Hosting . . . . . . .
6.12 How To Control APPLIST behaviour . . . .
7 Appendix
7.1 Appendix A . . . . .
7.1.1 Default values
7.2 Trademarks . . . . . .
7.3 Open Source Software
. .
for
. .
. .
. . . . . . . . . .
W2H parameters
. . . . . . . . . .
. . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
288
289
289
289
290
290
290
290
291
292
293
293
293
293
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
295
295
295
296
297
v
vi
Virtel User Guide, Release 4.57
VIRTEL User Guide
Warning: This is a draft version of the document.
Version : 4.57
Release Date : 08 Jan 2018. Publication Date : 08/01/2018
Syspertec Communication
196, Bureaux de la Colline 92213 Saint-Cloud Cedex Tél. : +33 (0) 1 46 02 60 42
www.syspertec.com
NOTICE
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 effort 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 companies mentioned in this document may be trademarks or registered trademarks of their
respective owners.
TABLE OF CONTENTS:
1
Virtel User Guide, Release 4.57
What’s new in Virtel 4.57
VIRTEL Web Access:
• Bidirectional presentation support.
• Enhanced font stretch mode. Optimization of screen size.
• Additional RACHECK support for ForceLUNAME
• Licence warning feature
• Enhancements to USSMSG10 support module
• Enhancements to Virtel Web Macro interface (VWM)
– Keyboard mapping enhancements
• Enhancements to Virtel Dynamic Directories Interface (DDI)
– Hotkey support for DDI macros
– New refresh options.
VIRTEL Web Modernisation & Integration:
• Enhancements to COPY$ NAME-OF. Support for TERMINAL, GROUP and RELAY items.
• Enhancements to DEFAULT-FILED-WITH-CURSOR statement.
Miscellaneous:
• Customizable HELP solution.
• DNS access to resolve IP address or DNS name.
• TCT option to support mixed case passwords
• Additional language support
• Batch export/import of RAW TRSF files.
Note: For further details see the Technical Newsletter: TN201706 - What’s new in Virtel 4.57.
2
TABLE OF CONTENTS:
CHAPTER
ONE
THE VIRTEL ENGINE
1.1 Introduction
1.1.1 What is Virtel
Simply put, Virtel is a host-based protocol converter that runs as a started task on the mainframe. At
the core of Virtel is the Virtel Engine which sits between host applications and external environments such
as the web or another external server. Virtel supports the following standard protocol - TCP/IP, SMTP,
HTTP/S, SOAP, MQ-SERIES, SNA, 3270, ICAL (IMS) and the inherited protocols - X25, XOT, XTP,
LU 6.2 to interface between host applications and external services. A classic example for Virtel would
be interfacing between legacy 3270 applications, running on the host, and the web. Virtel would provide
protocol conversion between data arriving from the browser is converted into a 3270 data-stream and sent
to the application. Users would no longer require 3270 terminal emulators products to interface with legacy
host applications. Access can now be provided through the users standard web browser. Various character
code page sets are supported, including DBCS character code sets.
The following diagram illustrates some of the protocols and applications supported by the Virtel Engine.
The Virtel Engine
3
Virtel User Guide, Release 4.57
Virtel provides three models. Web Access (VWA/W2H), Web Modernisation (VWM) and Web Integration
(VWI). In the next section each model is described in detail. Regardless of the model, Virtel’s mainframe
requirements are the same. The basic file requirements are as follows:• SAMP TRSF VSAM File. Contains the templates and web artefacts (JavaScript, Images, HTML, CSS
elements etc.) which are served to the browser.
• HTML TRSF VSAM File. Contains user customisation web artefacts (JavaScript, HTML, Images,
HTML, CSS elements etc.)
• LOADLIB PDS. Virtel load library
• ARBO VSAM File. Contains customer configuration data.
• Ancillary files. Statistics, logs, tracing etc.
Virtel normally runs as a started task on the mainframe. Multiple instances of Virtel can be run on the
same LPAR and can run within a SYSPLEX environment, benefiting from the load balancing services that
such environments provide. See the Virtel Installation manual for a full description of the Virtel mainframe
requirements. Virtel can also be run as a batch process, providing a “batch” service between external servers.
See the section Virtel Batch or the Virtel Connectivity Manual for further information on running Virtel in
batch.
Like any other web page servers Virtel responds to an incoming URL and serves template pages. The URL
targets one of the TCPIP ports that Virtel is listening on. The URL will identify the IP address of the
z/OS environment, and the port address will target the Virtel Instance. The pathname and parameters of
the URL will identify the Virtel Transaction that will be used to process the URL request. A URL example
is shown below. This is a URL requesting a connection to a CICS application called SPCICS. SPCICS is
the name of the Virtel transaction that will deal with the request. The pathname “/w2h/WEB2AJAX.htm”
identifies a Virtel 3270 template that will be used to support the transaction, providing the framework to
convert between 3270 data-stream and HTML presentations.
http://192.168.170.33:41002/w2h/WEB2AJAX.htm+SPCICS
For more information on the Virtel URL formats see the section Virtel URL Formats.
4
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.1.2 VIRTEL Web Access (VWA)
VIRTEL Web Access, formerly known as “Web-to-Host” (W2H), is a set of functions which provides access
to mainframe 3270 legacy applications via the user’s browser window. In the VWA model the Virtel Engine
comprises of two components, a HTTP server and a VTAM component serving the back-end VTAM legacy
applications, pertaining to operate as an LU2 device(s).
The principle operation of VWA is the production and delivery of 3270 data-streams as HTML pages. Static
template page and web elements supporting VWA are stored and maintained in a Virtel directory on the
mainframe at the host site. The pages served to the browser contain standard HTML tags, CSS, JavaScript
elements and HTML tags specific to VIRTEL. Invoked by a browser or a program, these pages form the basis
of an “on the fly” translation of 3270 data-streams, thus enabling the dynamic generation and delivery of a
3270 presentation to the browser. No terminal emulation software is required. The VWA model also includes
functions which allow dynamic modification of the original 3270 presentation, with the aim of making the
interface as “clickable” as possible. This chapter describes the set of functions required to support VWA
and presupposes a certain knowledge Web technologies and HTML page construction.
Some fundamental differences to standard terminal emulation protocol must be taken into consideration:
1. Sessions between a browser and the Virtel HTTP server are in disconnected mode, while they are in
connected mode between VIRTEL VTAM component and the host application.
2. The flow of information between the Virtel HTTP server and a client’s browser occurs on the initiative
of the client or through an optional ‘Long Poll’ asynchronous session.
3. A single request from the browser will only invoke a single response from the HTTP server, while the
transmission of a message to an application on the host may generate several response messages at
once (for example, a message to clear the screen followed by a new screen image).
These differences give rise to a need to ensure maintenance of session context between a client and a host
application. This is done by the SESSION-CODE tag embedded in the Virtel template pages. Although
the HTML pages used to display 3270 data contain specific VIRTEL tags, these pages can be developed
using standard web development tools. The pages containing VIRTEL specific tags are stored in a VIRTEL
directory along with other Virtel web elements such as Java Script modules, CSS style sheets and images.
The VIRTEL directory, known as the W2H directory, is located in the VSAM SAMP.TRSF file.
1.1. Introduction
5
Virtel User Guide, Release 4.57
Let’s look at how VWA works.
VWA Overview
1. The user enters a URL which points to the Virtel Engine.
In this case http:www.myHost.com/WEB2AJAX+TSO5. Virtel, running as a web server, will be listening on default port
80 for any incoming calls. When Virtel receives the call-in it will process the pathname of the URL
(/WEB2AJAX+TSO5) to determine a course of action.
2. The pathname /WEB2AJAX+TSO identifies a Virtel HTML page TEMPLATE (WEB2AJAX) and a
transaction. In this case the transaction is TSO. Virtel, through its configuration, recognizes the TSO
transaction as being a VTAM application and initiates a VTAM session with TSO.
3. A VTAM connection is established between TSO and Virtel with Virtel acting as a virtual terminal
relay between the browser and TSO. Subsequent HTML pages received from the browser will now be
converted to 3270 data streams and will be sent to TSO as if they had come from a 3270 terminal. 3270
data streams sent by the TSO application will be converted into HTML pages using the WEB2AJAX
template and sent to the browser.
4. TSO responds to the session request and sends a 3270 screen to Virtel.
5. Virtel, acting as a SLU in the VTAM session, receives the 3270 data stream from the host and constructs
a HTML web-page incorporating the 3270 data. It uses the HTML page WEB2AJAX.HTML as a
template. Virtel pages are maintained in the W2H directory located within the SAMP.TRSF VSAM
file.
6. The constructed HTML page is sent to the users browser.
7. The browser displays the page created by Virtel which will resemble a 3270 screen.
6
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
Features of Virtels VWA Presentation
A sophisticated and rich set of features are available with VWA through the use of the tool bar. Configuration
of the tool-bar is also possible. The following list summarizes the tool-bar features presented with the
standard VWA 3270 template:-
VWA 3270 Example
• Keyboard Controls. A user can send a variety of keyboard functions, such as PA2, ATTN,
etc. through the keyboard control.
• IND$FILE support.
Note: The IND$FILE function must not be considered as a replacement for a FTP client/server
architecture. Sending or receiving large files across this interface could result in performance
issues. Virtel provides a means of restricting file transfer sizes to avoid such a situation.
• Screen capture controls which provide a variety of capture options including 1/2/3 page-up
images within a single capture buffer.
• User setting controls enables an individual user to set their own Virtel controls and preferences.
• Macro Support. Enables a user to create macros to drive screen logic and repetitive tasks.
• Configurable help panels. Bespoke help panels can be developed to support business applications.
• Language support. Virtel supports a variety of different languages.
1.1. Introduction
7
Virtel User Guide, Release 4.57
1.1.3 VIRTEL Web Modernisation (VWM)
VIRTEL Web Modernisation, formerly known as “Host-Web-Services” (HWS), allows the presentation of
3270 host applications to be modified, without modifying the application itself. The presentation can be
adapted to a format (HTML, XML, Excel, etc.) suited to the requester, while hiding the details of navigation
within the 3270 transactions.
This function is implemented through a combination of the VIRTEL Web Access functions described in
Creating HTML and XML templates, and the Virtel scenario language described in Web Modernisation
VIRTEL Scenarios.
VIRTEL Web Modernisation allows “frozen” or “untouchable” 3270 transactions to be accessed by intermediate servers (n-tier architecture) or from a browser, while hiding the details of navigation within the
transactions. Variable input data for the transaction can either be included in the URL (GET method), or
sent as data with the HTTP request (POST method).
With modernisation, for example, several 3270 round trips can be made to the host application within a
presentation scenario before returning the final result to the browser. Data could be extracted from the
individual host responses and encapsulated into one HTML page. For example when a user requests a “list”
this could result in a sequence of key strokes and displays between the application and Virtel. Taking the
example:User enters "ASMITH" in CICS MAP as a search operand. Presses Enter.
First Screen returned.
User press PFK8 to obtain next screen.
Second screen returned.
User press PFK8 to obtain next screen.
Third screen returned. Last in sequence.
The above business logic i.e. “search for a name” can be incorporated into a Virtel Scenario as illustrated in
the diagram below. We have called the scenario GETDATA. The user enters the search argument “ASMITH”
and presses Enter. The HTML request is sent to Virtel. The HTML request, based upon the submitted
URL, is targeted towards transaction CUSTDATA which is a VTAM application transaction associated with
CICS6, a legacy CICS application. The CUSTDATA Virtel transaction is defined with scenario GETDATA.
This configuration data is maintained in the VIRTEL ARBO file.
8
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
When the user submits the URL from the browser Virtel will establishe a VTAM session with CICS6 and
then will continue to run the scenario GETDATA. The scenario contains the business logic which will perfom
the key stokes to obtain all the relevant data from multiple 3270 screens. The scenario will then build a
modernised web page which will contain a GUI “drop down list” encapsulating all data obtained from the
three 3270 CICS displays. The HTML response is sent back to the user.
The user has entered only one keystroke to submit the transaction and received one response. The data
within the HTML response will represent all the data extracted from several 3270 displays. The response
data will be presented in a “modernised” GUI fashion.
VWM Overview
1. The user enters a URL which identifies the Virtel transaction CUSTDATA.
2. The configuration data for the transaction CUSTDATA is loaded from the Virtel Configuration repository held within the Virtel ARBO VSAM dataset. The transaction CUSTDATA has a scenario
associated with it called GETDATA.
3. The GETDATA scenario is then used to navaigate through 3270 screens, collecting data from each
screen.
4. The scenarion builds a “clickable” GUI template using the data extracted from the three 3270 screens.
The template is presented to the browser.
5. The user has a modernised version of the original 3270 presentation incorporating a GUI drop down
from which they can navigate to the next sceen. A master/detail pattern has been deployed by
1.1. Introduction
9
Virtel User Guide, Release 4.57
the Virtel scenario, presenting the user with data from three separate 3270 screens. Modernisation
improves the users UX/UI presentation experince and by doing so enhances and improvers navigation
of the legacy business logic. Less network transfer is consumed as the number of original 3270 screens
is consolidated into one Virtel GUI master/detail screen.
10
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.1.4 VIRTEL Web Integration (VWI)
The objective of VIRTEL Web Integration, formerly known as “Host-for-Web” (H4W), is to allow a host
application to take maximum control of its web interface, for example through web services. This is in
complete contrast to VWA/VWM, whose objective is to avoid modification of host applications.
To control its web interface, an application has at its disposal primarily the 3270 screen, the VIRTEL table
variable facility, the HTML page template, and a set of VIRTEL commands contained in structured fields.
Additionally, for browser requests which enter VIRTEL using an entry point which specifies emulation type
“HOST4WEB”, the application can also use a set of VIRTEL control commands which can be embedded in
the 3270 screen via a BMS map, ISPF panel, or 3270 data stream. These HOST4WEB commands, available
from VIRTEL version 4.28 onwards, provide the same general functions as the structured field commands
in earlier versions.
Table variables, structured field commands, and HOST4WEB commands, are sent by the application to the
3270 session using standard methods (EXEC CICS SEND, ISPEXEC DISPLAY PANEL, TSO TPUT, etc).
VIRTEL intercepts and acts upon these commands, for example by selecting the page template or loading
data which can be referenced by VIRTEL orders embedded in the page templates and used to build lists of
values or data tables.
VMI enables an application to create a dynamic dialog between its transactions and web applications through
the creation of interactive bidirectional dialogs across the Internet between host (CICS, IMS, Ideal, Natural,
etc.) and server-based applications using XML/HTML web services or other communication procedures.
Incoming and outgoing Web Services Support
Incoming calls
• To expose host applications to web clients though web services, Virtel can be configured to:
• Receive and parse incoming web service calls
• Execute the appropriate transactions
• Receive data returned by the transactions in the form of screens, structured fields, COMMAREA, or
database segments
• Reformat and wrap that data with XML, JSON, HTML, SOAP, CSV, PDF, Word, JSON, etc.
• Serve it back to the web callers
Outgoing calls
• In the outgoing direction (host-initiated web services) the mechanism is the same, just reverse.
VWI can be configured to support a wide range of interfaces, protocols and APIs which can :• Expose mainframe applications and data as web services to web clients
• Invoke web services for the count of mainframe applications
• Support interactive exchange procedures between mainframe and web applications for cooperative work
• Function as a SOAP, MQ, PHP… server
• Transfer data blocks larger than 32KB, or blocks of data with variable format
• Convert data from DBCS (Double Byte Character Set) used by Japanese, Chinese, Russian… workstations or applications to EBCDIC, and vice/versa
• Serve 3270 data as international icons to eliminate natural languages from user interfaces
• Replace web connectors developed by IBM (CWS, CTG, HOD, IMS Connect, etc) and ISVs, or homegrown (CICS socket programming)
1.1. Introduction
11
Virtel User Guide, Release 4.57
VWI Overview
For more information, refer to the chapter “Programming Interfaces”.
1.1.5 VIRTEL Service Transactions
A Service Transaction is a long-running VIRTEL transaction which maintains a session with a host application and uses this session to serve a series of HTTP request / responses. Unlike a regular HTTP transaction,
which serves requests only from its originating user, identified by a specific VIRTEL SESSION-CODE, a
service transaction can serve a different user each time it processes an HTTP request. Service transactions
are typically used to provide fast access to public information such as the lists of field values displayed by
the “VIRTEL Suggest” feature.
A service transaction is started by an HTTP URL in exactly the same way as a regular transaction, but when
it has finished processing its first HTTP request, it indicates its readiness to serve another user, either by
means of the script command &) described under the heading “Transactions — Connection / Disconnection
Scripts” in the VIRTEL Connectivity Reference documentation, or by means of the ACTION$ SERVEANOTHER-USER command in a scenario.
A service transaction remains connected to the host application between input messages. It is then eligible
to process any HTTP request which specifies the same entry point and transaction name. Since service
transactions can potentially be used by many different users, a typical service transaction will provide
information which is not sensitive to being signed-on as a particular user.
12
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.2 VIRTEL URL Formats
1.2.1 Static pages
Virtel locates static HTML pages through the URL passed to the Virtel Engine and the configuration definitions defined within the Virtel ARBO VSAM file. An endpoint for Virtel is defined by a Virtel line definition
which identifies the TCP/IP port that Virtel listens on for incoming calls. By default Virtel uses two endpoints or ports, 41001 for Administration and port 41002 for user or client transactions. Each endpoint is associated with a default Entry Point; WEB2HOST in the case of 41001 and CLIWHOST for 41002. Transactions
are associated with End Points. An endpoint can be associated with more than one Entry Point. Virtel provides a Rule facility whereby an Entry Point can be selected by incoming call criteria - IP address for example.
Virtel Static Pages
Virtel stores pages and web elements within VIRTEL diretories located in TRSF VSAM files. The general
form of the URL for an HTML page stored in a VIRTEL directory is:
http://ipaddr:port/pathname/pagename
ipaddr:port Corresponds to the “Local ident” field of an HTTP line defined to VIRTEL. The rules of the
line are used to select the entry point. This entry point, which must specify emulation type HTML,
contains the list of transactions which the user is authorized to invoke.
pathname Represents a VIRTEL directory containing HTML pages or other elements. Refer to the section
“How the path name corresponds to a VIRTEL directory” below for details of how the pathname is
1.2. VIRTEL URL Formats
13
Virtel User Guide, Release 4.57
used to select the VIRTEL directory.
pagename Is the name of an element (HTML page, etc.) in the specified directory. VIRTEL converts the
element name to upper case (unless “case sensitive” is specified in the directory definition), and truncates the name if necessary to the maximum length specified in the directory definition (see “Directory
Management”).
VIRTEL also accepts certain abbreviated forms of the URL:
http://ipaddr:port/pathname
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described above. In this case, VIRTEL loads a default page
from this directory. The default page name is the same as the entry point name. Note: the trailing
slash is compulsory.
http://ipaddr:port/pagename
ipaddr:port Is the address of the HTTP line, as before.
pagename Is the name of a page to be loaded from the default directory. The default directory corresponds
to a default pathname equal to the entry point name.
http://ipaddr:port
ipaddr:port Is the address of the HTTP line, as before.
In this case, VIRTEL loads the default URL. VIRTEL obtains the default URL from the “TIOA at logon”
field of the default transaction. The default transaction is a type 4 transaction which has the same name as
the entry point. See example 7 below for an example of a default URL. If the “TIOA at logon” field of the
default transaction is blank, then VIRTEL loads the default page from the default directory. The default
page has the same name as the entry point, and the default directory corresponds to a default pathname
equal to the entry point name.
1.2.2 How the path name corresponds to a VIRTEL directory
The pathname specified in a VIRTEL URL is used to select a VIRTEL directory which contains
HTML page templates and other elements such as CSS stylesheets, JavaScript procedures, and
GIF or JPEG images. VIRTEL directories have a simple 8-character case-insensitive name,
whereas the pathname is expressed in Unix-style syntax (one or more casesensitive components separated by slashes), as is conventional for web applications. VIRTEL
must therefore translate the Unix-style pathname into a VIRTEL directory name.
The process of mapping a pathname to a VIRTEL directory name is carried out by means of
VIRTEL transactions which are defined under the entry point selected for each request by the
rules of the HTTP line. The entry point contains both processing transactions (application types
1, 2, and 3) and directory transactions (application type 4).
To find the directory which corresponds to the pathname, VIRTEL looks for a type 4 transaction
whose external name matches the first component of the pathname, and whose “Check URL
prefix” field is either blank or matches the start of the pathname. The name of the VIRTEL
directory is contained in the “Application name” field of the first such matching transaction found
under the entry point.
Note:
14
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
• The comparison of the first component of the pathname with the transaction external name
is case insensitive, and if the first component of the pathname is longer than 8 characters,
only the first 8 characters are compared.
• The comparison of the beginning of the pathname against the transaction’s “Check URL
prefix” field is case sensitive.
• The “Check URL prefix” field may contain “%20” to represent a blank and “?” to ignore a
character position.
• If the “Check URL prefix” field is completely blank it is considered to match any pathname
whose first component matches the transaction external name.
Examples
Assume that entry point WEB2HOST contains the following transactions:
Transactions under entry point WEB2HOST
In this example, transactions W2H-00, W2H-03*, W2H-05* are “application type 4” (directory transactions).
Other transactions, such as “application type 1” (processing transactions i.e. TSO, CICS, etc.) play no part
in the directory selection process.
The figure below shows an example of the detail of a directory transaction:-
1.2. VIRTEL URL Formats
15
Virtel User Guide, Release 4.57
Example of a directory transaction
Example 1: Neither pathname nor pagename specified
http://ipaddr:port
The pathname defaults to the entry point name, WEB2HOST, which matches transaction W2H-00. The
pagename also defaults to WEB2HOST. VIRTEL therefore fetches page WEB2HOST from the directory
W2H-DIR.
Example 2: pagename specified
http://ipaddr:port/menu.htm
The pathname defaults to the entry point name, WEB2HOST, which matches transaction W2H-00. VIRTEL
therefore fetches page menu.htm from the directory W2H-DIR.
Example 3: Pathname specified
http://ipaddr:port/w2h/user/
The pathname /w2h/user matches transaction W2H-04. The pagename defaults to the entry point name,
WEB2HOST. VIRTEL therefore fetches page WEB2HOST from the directory USR-DIR.
16
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
Example 4: Pathname and pagename specified
http://ipaddr:port/w2h/user/index.html
The pathname /w2h/user matches transaction W2H-03U. VIRTEL therefore fetches page index.html from
the directory USR-DIR.
http://ipaddr:port/home/user3/index.html
Example 5: Undefined pathname specified
http://ipaddr:port/w2h/badpath/index.html
In this case the pathname /w2h/badpath does not match any transaction. VIRTEL therefore rejects the
request.
Example 6: Partly-defined pathname specified
http://ipaddr:port/SECURE/misc/myPage.html
The pathname /SECURE/misc is not specifically defined to VIRTEL. However there is a transaction W2H-02
whose external name is SECURE and whose “Check URL prefix” field is blank, which matches all pathnames
whose first component is /SECURE. VIRTEL therefore fetches the any /SECURE/misc/myPage.html from
the designated directory W2H-DIR.
Example 7: Entry point with default URL
When a user connects to a VIRTEL line without specifying either pathname or pagename, as in the example
below, the entry point may be configured to redirect the request to a default URL:http://ipaddr:port
A default URL may be specified in the transaction whose external name is the same as the entry point name.
In the example type 4 transaction CLI-00 shown below, the default URL for the entry point CLIHOST is
//w2h/appmenu.htm+applist and thus the URL
http://ipaddr:port
is processed by VIRTEL as if
http://ipaddr:port//w2h/appmenu.htm+applist
had been specified.
1.2. VIRTEL URL Formats
17
Virtel User Guide, Release 4.57
Example of a default transaction with default URL
The entry point CLIWHOST can access the w2h directory through a directory definition specifing the
external directory path as an external name in the transaction. Here the transaction needs access to web
elements located in the W2H-DIR. The /w2h/ pathname in w2h/appmenu.htm matches the external name
of the directory transaction CLI-03W. This match defines a path to the W2H-DIR:-
18
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
Providing access to a directory through a transactions external name
1.2.3 Dynamic pages
The general form of the URL for a VIRTEL Web Access, VIRTEL Web Integration, or VIRTEL Web
Modernisation transaction is:
http://ipaddr:port/pathname/pagename+tranname
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of an element (HTML or XML) in the specified directory. This name may be
converted to upper case and truncated to the maximum length defined in the directory definition, as
previously described. This element is used as the “template page” into which VIRTEL inserts dynamic
data.
tranname Is the external name of a transaction defined under the entry point. The application program
(which may be a CICS transaction or other VTAM application, a VIRTEL sub-application, or an
external server) invoked by this transaction provides the dynamic data which VIRTEL inserts into the
template page.
Dynamic URL with userdata
A second form of URL allows user data to be passed to VIRTEL:http://ipaddr:port/pathname/pagename+tranname+userdata
ipaddr:port Is the address of the HTTP line, as before.
1.2. VIRTEL URL Formats
19
Virtel User Guide, Release 4.57
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of a template page, as before.
tranname Is the name of the transaction which provides the dynamic data for the template page.
userdata Is a character string which can be tested by the “User Data” field in the rules of the HTTP line
(see “Rules” in the VIRTEL Connectivity Reference documentation). This allows the administrator
to assign an entry point to the request based upon the contents of the userdata in the URL. The
userdata also becomes the value of the “routing parameter” associated with the tranname transaction.
The routing parameter can be referenced by the variable &1 in the “TIOA at logon” field of the
tranname transaction (see “Defining transaction parameters” in the VIRTEL Connectivity Reference
documentation). Additionally, if the rule which is selected specifies “$URL$” in its “Parameter” field,
and only if the HTTP terminal relays are defined in a logical pool (see “HTTP Terminals” under the
heading “Definition of an HTTP line” in the VIRTEL Connectivity Reference documentation), then
the routing parameter is used by VIRTEL to select a relay LU for the tranname transaction.
Dynamic URL with parameters
A third form of URL allows one or more parameters to be passed to a transaction by means of an “Input
Scenario” or by a “Connection / Disconnection Script”:
http://ipaddr:port/pathname/pagename+tranname?param1=value¶m2=value
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of a template page, as before.
tranname Is the name of the transaction which provides the dynamic data for the template page. This
transaction must be defined with the name of a presentation module in its “Output Scenario” field.
param1, param2, … These are the names of the parameters which the scenario can pick up using the
COPY$ INPUT-TO-VARIABLE or COPY$ INPUT-TO-SCREEN instructions (described 153) or
which can be substituted in a script by means of the &=paramn= system variable (see “Transactions – Connection / Disconnection Scripts” in the VIRTEL Connectivity Reference documentation.
The cumulative length of the URL parameters is limited by the BUFSIZE parameter of the VIRTCT.
If blanks or other special characters are required in the parameter value, then the special characters
must be coded in the standard URL escape format %xx where xx is the hexadecimal value of the
character in ASCII. For example, a blank is represented as %20.
Dynamic URL with userdata and parameters
A URL may contain both userdata and query parameters, as shown in the following example.
The various components of the URL have the same meaning as described in the preceding two
sections.
http://ipaddr:port/pathname/pagename+tranname+userdata?param1=value¶m2=value
20
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.2.4 3270 session management
VirtelSession parameter
Once a session has been established with the host 3270 application, the template page allows the user to
link to the next screen in the 3270 application dialog by means of a URL in the following format:
http://ipaddr:port/pathname/pagename++VirtelSession=sessionid
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of the template page to be used for displaying the next 3270 screen (usually the
same as the current template page).
sessionid Is a VIRTEL-generated code which allows VIRTEL to identify the user as being already connected
to an existing host session. The parameter VirtelSession=sessionid is inserted by the {{{SESSIONCODE}}} tag embedded in the template page (see “Session And Context Management”).
PrintVirtelSession parameter
A second form of the URL with SESSION-CODE allows display of print data sent by the application to the virtual printer associated with the specified session. Normally this URL will be
embedded in a template page and will be triggered by the {{{IF-PRINT-IS-READY}}} tag.
http://ipaddr:port/pathname/pagename++PrintVirtelSession=sessionid
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of the template page to be used for displaying the print data. This page must
contain the special {{{PRINT}}} tag (see “3287 Printing”) at the point at which the print data are
to be inserted in the page.
sessionid Is a code which allows VIRTEL to identify the printer associated with the user’s 3270 session.
The parameter PrintVirtelSession=sessionid (where sessionid is the associated 3270 session identifier),
is generated by the {{{SESSION-CODE}}} tag as in the following example:imprim.htm++Print{{{SESSION-CODE}}}
ValidateVirtelSession parameter
A third form of URL with {{{SESSION-CODE}}} allows a JavaScript procedure embedded in a template
page to determine whether there are pending updates to the 3270 screen image. For this type of URL,
VIRTEL returns no data, only an HTTP response code. The possible response codes are:
• 205 (Reset Content) The host application has updated the 3270 screen image since the last time it
was sent to the user.
• 304 (Not Modified) The host application has not updated the 3270 screen image
• 404 (Not Found) The sessionid code does not represent a valid host session.
Note: When response code 205 is indicated, the JavaScript procedure sends a further request to VIRTEL
to retrieve the updated 3270 screen image. This technique can be useful in handling host applications which
1.2. VIRTEL URL Formats
21
Virtel User Guide, Release 4.57
use multiple 3270 write commands to paint a single 3270 screen, where the user might otherwise be presented
with a partially updated screen. An example of this technique is contained in the WEB2VIRT.htm page
delivered in the VIRTEL sample directory W2H-DIR.
http://ipaddr:port/pathname/pagename++ValidateVirtelSession=sessionid
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename May be specified but is not used.
sessionid Is a code which allows VIRTEL to identify the 3270 session whose status is being queried. The
parameter ValidateVirtelSession=sessionid, where sessionid is the associated 3270 session identifier, is
generated by the {{{SESSION-CODE}}} tag as in the following example:check.htm++Validate{{{SESSION-CODE}}}
Note: For compatibility with previous versions, the keyword VerifyVirtelSession is also accepted. VerifyVirtelSession is similar to ValidateVirtelSession except that it produces only two possible return codes:
• 205 (screen updated)
• 304 (screen not updated or session invalid)
$UseCookieSession$ parameter
As an alternative to specifying the VirtelSession parameter in the URL, the SESSION-CODE may be sent
to VIRTEL in a cookie. An example URL is shown below:
http://ipaddr:port/pathname/pagename++$UseCookieSession$
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of the template page to be used for displaying the next 3270 screen (usually the
same as the current template page).
$UseCookieSession$ Indicates that the SESSION-CODE is contained in the VirtelSession cookie.
The VirtelSession cookie should be generated by Javascript as shown in the example below. This function
may be added to the custom Javascript script (see “Site customization of Javascript functions”):
/* Save VirtelSession cookie after each subpage is loaded */
function after_responseHandle(o, url, xtim) {
var node = document.getElementById("sesscode");
if (node) {
var text = node.textContent || node.innerText;
var sess = text.replace(/^VirtelSession=/i,"");
createCookie("VirtelSession", sess, 1);
}
}
Figure 1.5 Custom Javascript function to generate a VirtelSession cookie
22
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.2.5 Capability URLs
A URL may contain a “capability token” generated by another terminal. In this case the URL
inherits certain rights or capabilities conferred by the other terminal. The capabilities inherited
depend on the parameters specified in the SET-HEADER tag which generated the capability
token. For further details, see “Capability Tokens”.
http://ipaddr:port/pathname/pagename+tranname+capabilitytoken
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of a template page, as before.
tranname (optional) Is the name of the transaction which supplies the dynamic data for the page. If the
transaction name is omitted then two “+” signs must separate the pagename from the capabilitytoken.
capability token is a token which grants rights to another terminal’s resources. This code, whose format is
x-Virtel-name:token, is generated by the “{{{SET-HEADER}}}” tag. The code is case-sensitive and
so the capitalization must be exactly the same as the generated token.
1.2.6 Transmission of Security Tokens by URL
A security code, which identifies a user during a HTTP page upload request, is normally transmitted between
the browser and VIRTEL as a cookie (see “Uploading HTML Pages”). If, for security or other reasons, your
browser does not allow the use of cookies, then the security code can, as an alternative, be embedded in a
URL of the form shown below:http://ipaddr:port/pathname/pagename+tranname+securitycode
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of a template page, as before.
tranname Is the name of the transaction which supplies the dynamic data for the page.
securitycode Is the code which allows VIRTEL to identify the user. This code, whose format is VirtelCookie=xxxxxxxxxxxxxxxx, is generated by the “{{{SECURITY-TOKEN}}}” tag, as shown in the
example below:upload2.htm+upload+VirtelCookie={{{SECURITY-TOKEN}}}
The following format allows a static page to be displayed:
http://ipaddr:port/pathname/pagename++securitycode
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of the page.
securitycode Is a code of format VirtelCookie=xxxxxxxxxxxxxxxx which allows VIRTEL to identify the
user, as before.
On receipt of this URL, VIRTEL treats the VirtelCookie= parameter as if it were a cookie transmitted
by the browser.
1.2. VIRTEL URL Formats
23
Virtel User Guide, Release 4.57
1.2.7 Propagation of signon by URL
A URL embedded in a page sent by VIRTEL may contain a VirtelUserSignon parameter in order to propagate
the user’s signon credentials to another page. The value of the parameter is generated by the “({{{USERSIGNON-CODE}}} tag “. This can be useful in cases where the browser does not propagate the user name
and password from one page to another, for example when using VIRTEL transaction security type 4. The
format of a URL containing a signon code is shown below:http://ipaddr:port/pathname/pagename+tranname+VirtelUserSignon=signoncode
ipaddr:port Is the address of the HTTP line, as before.
pathname Represents a VIRTEL directory, as described earlier.
pagename Is the name of a template page, as before.
tranname Is the name of the transaction which supplies the dynamic data for the page.
signoncode Is a code which allows VIRTEL to identify the signed-on user. This code is generated by the
{{{USER-SIGNON-CODE}}} tag, as shown in the example below:http://web2virt.htm+cics+VirtelUserSignon={{{USER-SIGNON-CODE}}}
1.2.8 The Universal Transaction
A transaction may be defined with an external name consisting of an asterisk, and this is considered to be
a “universal” transaction. A universal transaction matches any URL not already matched by a preceding
transaction in the entry point. This allows VIRTEL to process URLs whose format does not conform to the
classic VIRTEL formats previously described.
24
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.3 Directory Management
HTML and XML template pages and other entities such as CSS stylesheets, JavaScript procedures, and GIF
or JPEG images used by VIRTEL Web Access are stored in directories within a VSAM KSDS managed by
VIRTEL. Each KSDS defined to VIRTEL can contain one or more directories. The system administrator
can upload pages and other elements into a VIRTEL directory by using a web browser or by e-mail, as
described in detail in the section “Uploading HTML Pages”.
1.3.1 Accessing the administration application
Virtel provides an administrative portal which contains various sub applications used to administer Virtel.
The administrative portal can be access either through the 3270 administration application or the HTML
GUI portal.
1.3.2 Access through 3270
Access to the 3270 application is through a normal VTAM logon using the VIRTEL APPLID as the application name. For example, from a VTAM screen enter LOGON APPLID=VIRTEL. The following screen
will appear:-
Logon screen for 3270 Administration
After logging in with security details the main application menu will be presented. Select PF1 from the main
menu to access the administration and configuration menu.
1.3. Directory Management
25
Virtel User Guide, Release 4.57
Directory sub application
The directory management sub-application allows the administrator to define directories. The subapplication is accessible by [PF6] from the configuration menu, or by [PF12] from the system services menu
followed by option 3, or from the VIRTEL Multi-Session menu via a transaction which invokes VIRTEL
module VIR0042.
1.3.3 Security
If security is active, access to the directory management sub-application from the configuration menu or the
system services menu is controlled by resource $$PCPC$$.
When invoked via a transaction, normal transaction security rules apply.
In addition, each directory is protected by a resource whose name is the same as the directory name. The
administrator must have access to this resource in order to view or manage the contents of the directory, or
to upload pages to the directory. When an external security product is used, the resource is defined in the
class named by the RNODE parameter in the VIRTCT (see “Parameters of the VIRTCT” in the VIRTEL
Installation Guide).
Security management is described in the VIRTEL Security documentation.
1.3.4 Creating, modifying, and deleting directories
When the directory management sub-application is invoked, it displays a list of the directories already defined
in the system:-
26
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
Figure 1.6 Directory management summary screen
Using the associated Admin(3270) functions
These functions are accessed from either the browsers Administration portal or by logging on to Virtel using
it’s VTAM interface.
Deleting a directory definition
To delete a directory definition, place the cursor on the name of the directory to be deleted and press [PF2].
The message CONFIRM DELETE appears at the bottom of the screen. Press [PF2] again. The message
DELETE OK indicates that the deletion of the directory definition was successful. While the message
CONFIRM DELETE is displayed, you can press any function key other than [PF2] to cancel the operation.
Displaying directory contents
To display the contents of a directory, place the cursor on the directory name and press [PF4]. VIRTEL
displays the directory contents management screen described below.
Adding a directory definition
To create a new directory definition, place the cursor on the blank line after the last directory, and press
[PF12] to display an empty directory detail screen. Fill in all of the fields and press [ENTER]. The message
CREATION OK indicates that the directory definition was successfully created.
1.3. Directory Management
27
Virtel User Guide, Release 4.57
Scrolling the list of directories
To scroll to the top of the list, press [PF6]. To scroll up or down the list, press [PF7] or [PF8].
Exiting from directory management
To return to the configuration menu, press [PF3].
1.3.5 Defining directory parameters
To access the detail screen for any directory, place the cursor on the directory name and press [PF12]:
Directory management detail screen
Name The name of the directory as known by VIRTEL. If security is active, this name must also be defined
as a resource to which the user must be authorized.
Description Comment associated with the directory.
Type V (or blank) indicates that the directory is held in a VSAM KSDS.
DD name The file name of the VSAM KSDS which contains the directory. This name must be defined in
one of the UFILEn parameters in the VIRTCT, and a DD statement with the same name must appear
in the VIRTEL started task JCL.
Keyword This is an 8-byte key which allows multiple directories to be stored within a single VSAM KSDS.
Each directory in a KSDS must have a unique key.
Size of names The maximum length of the names of HTML pages and other elements stored in this
directory. The minimum (and default) value is 8. The maximum value is 64.
28
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
Case Any non-blank character in this field indicates that the element names stored in this directory are
case sensitive. Blank indicates that the names are not case sensitive.
Copy up This field is used by VIRTEL/PC. For VIRTEL Web Access directories, the value X must be
coded.
Copy down This field is used by VIRTEL/PC. For VIRTEL Web Access directories, the value X must be
coded.
Delete This field is used by VIRTEL/PC. For VIRTEL Web Access directories, the value X must be coded.
After pressing [PF4] at the directory management summary screen or detail screen, VIRTEL displays
a list of the files in the directory:
Figure 1.8 Directory contents management screen
1.3.6 Associated functions
Deleting an element
To delete an element from a directory, place the cursor on the name of the element to be deleted and
press [PF2]. The message CONFIRM DELETE appears at the bottom of the screen. Press [PF2] again.
The message DELETE OK indicates that the deletion of the element was successful. While the message
CONFIRM DELETE is displayed, you can press any function key other than [PF2] to cancel the operation.
Copying an element to another directory
To copy an element from directory A to directory B, first display the contents of directory A. In field [7]
type the name of the target directory B, then press [ENTER]. Next, place the cursor on the name of the
element to be copied, then press [PF6]. The message COPY COMPLETED indicates that the operation
1.3. Directory Management
29
Virtel User Guide, Release 4.57
was successful. If the element exists in the target directory, the copy fails and the message THIS FILE IS
ALREADY IN THE TARGET DIRECTORY is displayed at the bottom of the screen.
Scrolling the list
The list of elements can be scrolled up and down using [PF7] and [PF8].
Exiting from directory contents management
To return to the list of directories, press [PF3].
1.3.7 Acccess administration portal via the web
Access to the HTML GUI Administration portal is through the web using the Administration endpoint. By
default this is port 41001. The URL http://192.168.129.33:41001 is an example of a URL to access the WEB
administration portal. After providing security information the following screen will appear:-
Logon screen for Web Administration
Selecting the Admin (HTML) will prompt for a userid and password. After providing security details the
following administration portal will appear:-
30
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
Web Administration Portal
Directory administration can be invoked from the Directory link. Selecting a directory will display
a content menu proving options to list, edit, delete or create new directories.
1.3. Directory Management
31
Virtel User Guide, Release 4.57
Directory Context Menu
When selecting a directory, the detail panel will be displayed. The ICONs on the right hand side of the title
bar provide actions such as add, update or list.
Directory Detail Display
32
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
1.4 Creating Virtel Template Pages
1.4.1 Introduction
Template pages are the means by which VIRTEL presents host application data to the user via a web
browser. In addition to standard HTML or XML tags, template pages contain VIRTEL-specific tags enabling
integration of information delivered by the mainframe application programs. HTML template pages may
contain GIF or JPEG images, sounds, scripts such as JavaScript or any other function or program elements
that are compatible with the browser. Template pages may be produced either by hand or by using standard
HTML or XML design tools available on the market.
For VWA, users would not be required to produce or modify any template pages as all the necessary template
pages are provided by the Virtel product. For VWM or VWI, new pages may be produced by Virtel tools
such as Virtel Screen Redesigner to support modernisation or integration projects. Virtel Studio may also
introduce new templates to support business logic in Virtel scenarios. Sometimes it may be necessary to
modify these pages.
The following sections provide details on Virtel tags.
1.4.2 Defining the tag delimiters
VIRTEL-specific tags are used to insert data originating at the host into an HTML or XML page, and to
manage colours and function keys in an HTML page. VIRTEL-specific tags are identified by special begin
and end delimiters. The delimiters themselves are defined by means of a comment placed between the tags
and of the HTML page. The actual delimiters may vary from one page to another.
In this example, VIRTEL-specific tags are defined as being represented by a succession of 3 opening braces
and terminated by a succession of 3 closing braces. This convention is maintained throughout the remainder
of this chapter. A minimum template required for Virtel to work with and display a 3270 application looks
something like this:
Virtel Unplugged - Example 1
Sample Virtel Template
Note: See the use of the Virtel tags {{{ }}} within the HTML template. Virtel injects data into these
fields before sending the template to the browser.
1.4.3 Session and context management
VIRTEL uses the concept of a session code to maintain the context between a client using a browser and
the host application to which the client is connected. This code allows VIRTEL to identify the client and to
associate the client with a session already established with a host application.
SESSION-CODE tag
The SESSION-CODE tag is used to create the URL associated with form submission.
{{{ SESSION-CODE }}}
The SESSION-CODE tag allows a session code to be inserted in the template page in the format VirtelSession=xxxxxxxxxxxxxxxx. The value of the session code changes after each message. For examples of its use,
see “Transmitting Data To The Host”, and “3287 Printing”.
AJAX-SESSION-CODE tag
The AJAX-SESSION-CODE tag is similar to the SESSION-CODE tag, but it generates the code in a
different format which does not change with each request. This is useful when implementing an AJAX
dialog between the application and the browser. For this type of application, it is not always possible to
transmit the VIRTEL session code to the browser, especially if a Javascript library is used.
{{{ AJAX-SESSION-CODE }}}
The AJAX-SESSION-CODE tag allows a session code to be inserted in the template page in the format
AjaxSession=xxxxxxxxxxxxxxxx. For example:result.txt+cics+{{{ AJAX-SESSION-CODE }}}
SET-INITIAL-TIMEOUT tag
The SET-INITIAL-TIMEOUT tag allows a timeout to be started when VIRTEL builds the page.
34
Chapter 1. The Virtel Engine
Virtel User Guide, Release 4.57
{{{ SET-INITIAL-TIMEOUT "n" }}}
For example, if the instruction
{{{ SET-INITIAL-TIMEOUT "10" }}}
is coded in a page or a sub-page, then VIRTEL will cancel the session if the workstation has not sent another
request after 10 seconds.
1.4.4 Transmitting data to the host
Transmission of data to the host uses the principle of sending an HTML form. In conjunction with the
SESSION-CODE tag, the form allows the transmission of input fields to the host application, and the
display of the subsequent application screen.
The form is defined as follows:
name Form name. The name of the form is used in JavaScript procedures to refer to various elements of
the form. For an example, see the section “Cursor management”.
action URL transmitted to the server, in the following format:
action="pagename++{{{SESSION-CODE}}}"
pagename Is the name of the template page to be used to display the subsequent screen sent by the host
application (usually the same as the current template page)
SESSION-CODE Identifies the session established with the host application
method Transmission mode. Always POST.
Example :
. In order to minimise traffic, it is also advisable to place only useful data in
the tag fields for example, generated fields or copies resulting from GENERATE-HTML and COPY-FROM
tags, as well as indispensable fields such as focusField and pfkField. Other data may be placed anywhere in
the area of the HTML page, provided that their position conforms to the standards. The following presents
a template structure example.
35
Virtel User Guide, Release 4.57
.GREEN {font-family: monospace; background: #000000; color: #00FF00; }
//-->
{{{ON-ATTRIBUTE (PROTECTED,WHITE)}}}
{{{ON-END-OF-ATTRIBUTE (PROTECTED,WHITE)}}}
{{{ADD-TO-FIELDS (NORMAL,NOCOLOR) class="GREEN" }}}
{{{DEFINE-HTML-PFKEY "PFKFIELD"}}}
{{{DEFINE-HTML-FOCUS-FIELD "FOCUSFIELD"}}}