TM
Commerce Server/400
User's Guide
Version 1.0
COPYRIGHT c 1996 I/NET, INC.
Revision A
Copyright c 1996 I/NET, Inc. All Rights Reserved.
No part of this book may be reproduced in any form or by any
means, electronic or mechanical, including photocopying
without written permission from I/NET, Inc.
Commerce Server/400 is a trademark of I/NET, Inc. Other
brand and product names are trademarks or registered
trademarks of their respective holders.
Commerce Server/400 Table of Contents
Table of Contents
1. GETTING STARTED .......................................10
1.1 MIGRATION ...........................................11
1.1.1 End Web Server/400 Before Installation ..........11
1.1.2 Migrating From Web Server/400 Version 1.2. ......11
1.1.3 Migrating From a Web Server/400 Version Prior to
1.2 ...................................................12
1.2 INSTALLATION ........................................13
1.2.1 Installing Web Server/400 or Commerce Server/400 13
1.2.2 Objects Installed ...............................15
1.3 HARDWARE CONFIGURATION ..............................17
1.3.1 Hardware Requirements ...........................17
1.3.2 Network Configurations ..........................17
1.3.3 Web Server/400 over a LAN .......................17
1.3.4 Web Server/400 over the Internet - LAN Router ...18
1.3.5 Non-Network Configurations ......................18
1.4 SOFTWARE CONFIGURATION ..............................19
1.5 TCP/IP CONFIGURATION TIPS ...........................20
1.5.1 TCP/IP Terms ....................................20
1.5.2 Assigning your AS/400 an IP Address .............21
1.5.3 Working with the OS/400 commands to configure
TCP/IP ................................................22
1.5.4 Starting and Testing your TCP/IP Configuration ..24
1.5.5 Host Names ......................................24
1.6 STARTING THE SERVER .................................27
1.6.1 Starting Web Server/400 or Commerce Server/400 ..27
1.6.2 Accessing the Server ............................27
1.7 VIEWING WEB SERVER/400 DOCUMENTATION FROM A BROWSER .29
1.7.1 Accessing Document Files Directly ...............29
1.7.2 Accessing Documentation through Web Server/400 ..29
1.8 TESTING THE SETUP ...................................30
1.9 WHERE TO GO FROM HERE ...............................32
1.9.1 New since Web Server/400 Version 1.2 ............32
1.10 SETTING UP COMMERCE SERVER/400 .....................34
1.10.1 Overview .......................................34
1.10.2 Obtaining a Server Certificate .................34
1.10.3 Enabling Commerce Server/400 to do SSL .........38
1.10.4 Start the Server ...............................39
1.10.5 Testing the Server .............................39
1.10.6 Test and Evaluation Server Certificates ........40
2. USING COMMERCE SERVER/400 .............................43
2.1 WHAT IS A WEB SERVER? ...............................44
2.1.1 Introduction ....................................44
2.1.2 A Web Server's Role .............................44
2.1.3 Who Deals with a Web Server? ....................45
2.1.4 Hypertext Transfer Protocol Basics ..............46
2.2 WHAT IS A COMMERCE SERVER? ..........................47
2.2.1 Overview ........................................47
2.2.2 Commerce Serving Basics .........................48
Page 3
Commerce Server/400 Table of Contents
2.2.3 How Does Commerce Server/400 Do This? ...........50
2.3 URL LOCATIONS .......................................53
2.3.1 OS/400 File Systems .............................53
2.3.2 Uniform Resource Locator ........................53
2.3.3 How Web Server/400 Finds a Web Document .........54
2.3.4 Special URL-paths ...............................56
2.3.5 Root URL-Paths ..................................57
2.3.6 QDLS URL-Paths ..................................57
2.3.7 QSYS URL-Paths ..................................58
2.3.8 USF URL-Paths ...................................60
2.3.9 Spooled File URL-Paths ..........................61
2.3.10 Dynamic Indexing URL-Paths .....................61
2.3.11 OS/400 File Systems ............................63
2.3.12 Symbolic Links .................................64
2.4 ALIASES .............................................65
2.4.1 Mapping a URL-Path to a Different Location ......65
2.4.2 Using Aliases to Access Other File Systems ......66
2.4.3 Using Aliases to Access Special Web Documents ...67
2.4.4 Using Aliases to Redirect URLs to Different Servers67
2.4.5 Alias Matching ..................................68
2.5 NLS ARCHITECTURE ....................................71
2.5.1 NLS Definitions .................................71
2.5.2 Serving Content .................................72
2.5.3 Serving Webulator Screens .......................72
2.5.4 Reading Configuration Files .....................72
2.5.5 Conversion Methods ..............................72
2.5.6 CCSIDs and ISO character sets ...................73
2.5.7 Limitations .....................................73
2.5.8 Related Documentation ...........................74
2.5.9 Flow of Text Conversion .........................74
2.6 CREATING CONTENT ....................................77
2.6.1 Location for files on your AS/400 ...............77
2.6.2 Using FTP to Move Your Content ..................77
2.6.3 Client Access ...................................80
2.7 USER DIRECTORIES ....................................82
2.7.1 User Directory Example ..........................82
2.7.2 Home Directory ..................................83
2.8 ACCESSING DATABASE FILES ............................84
2.8.1 Database File Support ...........................84
2.8.2 Specifying keyword parameters ...................84
2.8.3 Accessing Source Physical Files .................85
2.8.4 Accessing Save Files ............................88
2.8.5 Accessing Physical and Logical Files ............90
2.9 CGI SCRIPTS ........................................102
2.9.1 Flow of a CGI Script ...........................102
2.9.2 Script Concepts ................................103
2.9.3 CGI Environment Variables ......................104
2.9.4 Script Inputs ..................................107
2.9.5 Script Outputs .................................110
2.9.6 Status Codes ...................................114
2.9.7 Script APIs ....................................115
2.9.8 Creating Script Programs .......................130
2.10 ACCESSING SPOOLED FILES ...........................134
2.10.1 Spooled File Support ..........................134
Page 4
Commerce Server/400 Table of Contents
2.10.2 Specifying a URL ..............................134
2.10.3 Determining Content Type ......................135
2.10.4 Authority .....................................135
2.10.5 Supported Keywords ............................136
2.10.6 Output Considerations .........................138
2.10.7 Restrictions ..................................138
2.10.8 Examples ......................................138
2.11 ULTIMEDIA SYSTEM FACILITIES .......................140
2.12 IMAGE MAPPING FEATURE .............................141
2.12.1 Including a Mapped Image ......................141
2.12.2 Configuration Issues ..........................141
2.12.3 Using Your Own Image Mapping ..................142
2.13 CONTENT TYPES .....................................143
2.14 DYNAMIC INDEXING ..................................144
2.14.1 Dynamic Indexing ..............................144
2.14.2 Disabling Dynamic Indexing ....................144
2.14.3 Features of Dynamic Indexing ..................145
2.15 PROTECTING YOUR AS/400 INFORMATION ................150
2.15.1 OS/400 Authority ..............................151
2.15.2 Web Server/400 Scope Control ..................151
2.15.3 Web Server/400 Access Control .................152
2.15.4 Further Information About Protecting Your AS/400153
2.15.5 Authentication User Storage ...................154
2.15.6 Access Control Tutorial .......................155
2.15.7 Access Control Example ........................159
2.15.8 How Limit Sections Are Evaluated ..............161
2.16 LOGS ..............................................163
2.16.1 Server User Profile Authority Considerations ..163
2.16.2 Migration Notes for Version 1.0 Customers Logging
to Log Files within QSYS .............................164
2.16.3 Log Cycling ...................................164
2.16.4 Access Log ....................................166
2.16.5 Statistics Logs ...............................170
2.16.6 Error Log .....................................176
2.17 SERVER-SIDE INCLUDES ..............................179
2.17.1 What are Server-Side Includes? ................179
2.17.2 Which Files are Parsed? .......................179
2.17.3 Server-Side Include Format ....................179
2.17.4 Supported Tags ................................180
2.17.5 Time Format Special Characters ................186
2.18 ADMINISTRATION MODE ...............................187
2.18.1 What is the Administration Mode? ..............187
3. COMMANDS .............................................193
3.1 WEB SERVER COMMANDS ................................194
3.1.1 Web Server/400 Commands ........................194
3.2 OPERATIONAL COMMANDS ...............................197
3.2.1 STRWWW .........................................197
3.2.2 ENDWWW .........................................202
3.2.3 STRWWWRP .......................................204
3.2.4 ENDWWWRP .......................................205
3.3 CONFIGURATION COMMANDS .............................207
3.3.1 CHGWWWCFG ......................................207
Page 5
Commerce Server/400 Table of Contents
3.3.2 SETWWWCFG ......................................209
3.3.3 WRKWWWINCL .....................................210
3.3.4 ADDWWWINCL .....................................211
3.3.5 CHGWWWINCL .....................................211
3.3.6 WRKWWWICON .....................................212
3.3.7 ADDWWWICON .....................................213
3.3.8 CHGWWWICON .....................................213
3.3.9 WRKWWWMAP ......................................214
3.3.10 ADDWWWMAP .....................................215
3.3.11 CHGWWWMAP .....................................215
3.3.12 DLTWWWMAP .....................................215
3.3.13 WRKWWWSCPL ....................................216
3.3.14 ADDWWWSCPL ....................................216
3.3.15 CHGWWWSCPL ....................................217
3.3.16 WRKWWWALS .....................................217
3.3.17 ADDWWWALS .....................................218
3.3.18 CHGWWWALS .....................................218
3.3.19 DLTWWWALS .....................................218
3.3.20 WRKWWWCTP .....................................219
3.3.21 ADDWWWCTP .....................................220
3.3.22 CHGWWWCTP .....................................220
3.3.23 DLTWWWCTP .....................................220
3.3.24 WRKWWWUSR .....................................221
3.3.25 ADDWWWUSR .....................................221
3.3.26 CHGWWWUSR .....................................222
3.3.27 DLTWWWUSR .....................................222
3.3.28 MIGWWWUSR .....................................222
3.3.29 WRKWWWDIR .....................................224
3.3.30 WRKWWWLIM .....................................225
3.3.31 CHGWWWDIR .....................................226
3.3.32 Common Configuration Command Parameters .......227
3.4 COMMERCE SERVER COMMANDS ...........................230
4. CONFIGURATION VALUES .................................238
4.1 ALL CONFIGURATION VALUES BY CATEGORY ...............239
4.1.1 Access Control .................................239
4.1.2 Aliases ........................................239
4.1.3 Commerce Server Support ........................239
4.1.4 Content Types ..................................240
4.1.5 Document Locations .............................240
4.1.6 Dynamic Indexing ...............................240
4.1.7 Image Mapping ..................................240
4.1.8 Include Libraries ..............................240
4.1.9 Logs ...........................................240
4.1.10 Request Processing ............................241
4.1.11 Scripts .......................................241
4.1.12 Server Administration .........................241
4.1.13 User Directories ..............................242
4.1.14 Webulator Support .............................242
4.2 ACCESS CONTROL .....................................243
4.2.1 Administrative Access Control File Path
Configuration ........................................243
4.2.2 Allow Hosts ....................................244
Page 6
Commerce Server/400 Table of Contents
4.2.3 Authentication Group Entry .....................245
4.2.4 Authentication Group File Configuration ........246
4.2.5 Authentication Realm Name Configuration ........247
4.2.6 Authentication Password Storage ................248
4.2.7 Authentication Type Configuration ..............249
4.2.8 Authentication User Entry ......................249
4.2.9 Authentication User File Configuration .........250
4.2.10 Deny Hosts ....................................251
4.2.11 Directory Section End .........................253
4.2.12 Directory Section Start .......................254
4.2.13 Directory Based Configuration File Path .......255
4.2.14 Limit Section End .............................256
4.2.15 Limit Section Start ...........................257
4.2.16 Order .........................................258
4.2.17 Require User Authentication Configuration .....259
4.3 ALIASES ............................................261
4.3.1 Alias ..........................................261
4.3.2 Alias File Path ................................262
4.4 COMMERCE SERVER SUPPORT ............................264
4.4.1 Commerce Key List File Path ....................264
4.4.2 Commerce Session Cache Size ....................265
4.4.3 Commerce Session Cache Timeout .................265
4.4.4 Commerce SSL Port ..............................266
4.4.5 SSL Version ....................................267
4.5 CONTENT TYPES ......................................269
4.5.1 Content Type Entry .............................269
4.5.2 Content Type File Path .........................270
4.6 DOCUMENT LOCATIONS .................................271
4.6.1 Default Content Type ...........................271
4.6.2 Document Root Path .............................271
4.6.3 Document Root QDLS .............................272
4.6.4 Document Root QSYS .............................273
4.6.5 Server Root Path ...............................274
4.6.6 System Icon Paths ..............................275
4.7 DYNAMIC INDEXING ...................................277
4.7.1 Add Description ................................277
4.7.2 Index Default View .............................278
4.7.3 Index Exclude ..................................279
4.7.4 Index Footer File Path .........................280
4.7.5 Index Header File Path .........................281
4.7.6 Index Icon Files ...............................282
4.7.7 Index Style ....................................284
4.7.8 Send Directory Content Length ..................285
4.8 IMAGE MAPPING ......................................287
4.8.1 Circle .........................................287
4.8.2 Default ........................................287
4.8.3 Image Map File Entry ...........................288
4.8.4 Image Map File Path ............................289
4.8.5 Point ..........................................289
4.8.6 Poly ...........................................290
4.8.7 Rect ...........................................291
4.9 INCLUDE LIBRARIES ..................................292
4.9.1 Include Library ................................292
4.10 LOGS ..............................................293
Page 7
Commerce Server/400 Table of Contents
4.10.1 Access Log Cycle Configuration ................293
4.10.2 Access Log File Path ..........................294
4.10.3 Error Log Cycle Configuration .................295
4.10.4 Error Log File Path ...........................297
4.10.5 Error Logging Level ...........................298
4.10.6 Statistics Log Cycle Configuration ............299
4.10.7 Statistics Log File Path ......................300
4.10.8 Statistics Raw Data Path Configuration ........301
4.11 REQUEST PROCESSING ................................303
4.11.1 Connection Queue Size .........................303
4.11.2 Initial Request Processors ....................303
4.11.3 Maximum Request Processors ....................304
4.11.4 Request Wait Timeout ..........................305
4.11.5 Timeout .......................................306
4.12 SCRIPTS ...........................................308
4.12.1 Enable Scripts ................................308
4.12.2 Script Library ................................309
4.13 SERVER ADMINISTRATION .............................310
4.13.1 Allowed Protocols .............................310
4.13.2 Content CCSID .................................311
4.13.3 Default Source Type ...........................311
4.13.4 Disable Server ................................312
4.13.5 Domain Name Lookup ............................313
4.13.6 File CCSID ....................................314
4.13.7 Index Name ....................................315
4.13.8 Initial Library List ..........................316
4.13.9 MultiHome .....................................317
4.13.10 Send File Content Length .....................319
4.13.11 Send File Modification Date ..................320
4.13.12 Send Server Version ..........................320
4.13.13 Server Host Name .............................321
4.13.14 Server Identifier ............................322
4.13.15 Server Protocols .............................323
4.13.16 Server Side Include Configuration ............324
4.13.17 Server User Profile ..........................324
4.13.18 Socket Port ..................................326
4.13.19 Temporary Directory ..........................326
4.14 USER DIRECTORIES ..................................328
4.14.1 Public User Directory .........................328
4.15 WEBULATOR SUPPORT .................................329
4.15.1 Maximum Sessions ..............................329
4.15.2 Webulator User File Path ......................329
4.15.3 Disable Webulator .............................330
5. CONFIGURATION FILES ..................................332
5.1 CONFIGURATION FILES ................................333
5.1.1 Creating a New Configuration File ..............333
5.1.2 Rules About Configuration Files in General .....333
5.1.3 Authority ......................................333
5.1.4 Specific Configuration Files ...................333
5.1.5 File Relationships .............................334
5.2 SIMPLE FILES .......................................336
5.2.1 Master Server Configuration File ...............336
Page 8
Commerce Server/400 Table of Contents
5.2.2 Alias Configuration File .......................339
5.2.3 Content Type Configuration File ................340
5.3 IMAGE MAPPING ......................................341
5.3.1 Global Image Map Configuration File ............341
5.3.2 Image Map Mapping File .........................341
5.4 ACCESS CONTROL .....................................343
5.4.1 Directory Based Configuration File .............343
5.4.2 Administrative Access Configuration File .......344
5.4.3 User Authenticaton User Stream File ............345
5.4.4 User Authenticaton User Database File ..........345
5.4.5 User Authentication Group Configuration File ...346
5.5 HOW TO CONFIGURE THE SERVER ........................347
5.5.1 Configuring the Server Through Commands ........347
5.5.2 Configuring the Server by Editing Configuration
Files ................................................347
6. INDEX OF CONFIGURATION KEYWORDS ......................348
7. COMPLETE INDEX .......................................351
Page 9
Commerce Server/400 1.0 Getting Started
1. Getting Started
Page 10
Commerce Server/400 1.0 Getting Started
1.1 Migration
Note: If you are running Commerce Server/400, consider the
references to Web Server/400 in this documentation to mean
Commerce Server/400. Both products are interchangeable
except for the security enhancements added to Commerce
Server/400.
1.1.1 End Web Server/400 Before Installation
All currently running Web servers must be ended with the
ENDWWW command before installing the Web Server/400 or
Commerce Server/400 upgrade. Also ensure that no product
commands or menus are running. Use the WRKACTJOB command to
verify there are no servers and commands running.
You may see older version restored (CPF3722) messages in the
joblog when migrating to the new version. These messages are
normal and are generated because one or more of the product
libraries have been backed up with a save command that had
the update history (UPDHST) parameter set to *YES.
1.1.2 Migrating From Web Server/400 Version 1.2.
This section should be read by all customers migrating from
a previous version of Web Server/400.
Evaluate authorization user storage
If you are using user authentication, read about user
storage (section 2.15.5 on page 154) and decide whether
you want to migrate (section 3.3.28 on page 222) stream
files to database files.
Update the Content Type Configuration File
A new content type was added to the content type
configuration file. Using the WRKWWWCTP command, find the
current entry for application/octet-stream and add the
extensions using option 2.
Content type Extensions
--------------------------- -------------
application/octet-stream exe dll
Evaluate default CCSIDs
The Content CCSID (section 4.13.2 on page 311) default
has changed from 850 to 819. The new File CCSID (section
4.13.6 on page 314) configuration value also defaults to
819. This should work better for most users than the old
way. If you wish, you can override the defaults.
Page 11
Commerce Server/400 1.0 Getting Started
Server Administrator Address Has Been Removed
This configuration value has been removed. As it was not
being used previously, this should not be noticable to
most users. If, however, you have a program which sets
this value through the CHGWWWCFG (section 3.3.1 on page
207) command, you will need to change the program.
Consider changing Domain name lookup (section 4.13.5 on page
313).
The default for this is Normal, which looks up a host
name for every request. For performance, we ship a
configuration file to all new customers that sets this to
Minimal.
1.1.3 Migrating From a Web Server/400 Version Prior to 1.2
This section should be read by all customers migrating from
a version of Web Server/400 earlier than version 1.2. Make
the changes below, then make the changes suggested for users
of Web Server 1.2.
Using a Server User Profile other than WWWUSER
If you are using a server user profile other than the
default of WWWUSER, then that user profile's job
description needs to be changed to WWWSERVER/WWWJOBD.
More information on this can be found under the STRWWW
command.
Updating the Content Type Configuration File
A couple of new content types were added to the content
type configuration file. Using the WRKWWWCTP command,
find the current entry for each of the content types
listed below and add the specified extensions using
option 2.
Content type Extensions
--------------------------- -------------
application/octet-stream pcl
text/html html3 ht3
Updating from Version 1.0
Customers updating directly from version 1.0 should
follow the migration instructions provided separately. If
you are not sure what version you are running, display
the data area WWWSERVER/VERSION using the command
DSPDTAARA WWWSERVER/VERSION. If this data area does not
exist, you are probably running version 1.0.
Page 12
Commerce Server/400 1.0 Getting Started
1.2 Installation
1.2.1 Installing Web Server/400 or Commerce Server/400
1.2.1.1 Important Pre-Installation Instructions
Checking Your Tape Device
We have identified a problem in V3R1 on systems that have
migrated/slip-installed from V2R3 to V3R1. The new SAV and
RST commands CPF with a CPF3768 (i.e., Device not valid for
command) when a valid IFS path for the tape device is
provided. Since the server installation uses the RST
command, the following steps need to be performed to ensure
a successful installation:
1.Use the following command to display the tape device
using an IFS path:
WRKLNK '/QSYS.LIB/xxxxx.DEVD'
where xxxxx is your tape device (e.g., TAP01)
2.If the attribute of the tape device is set to TAP you
are okay and can proceed with the installation.
Otherwise you must delete and re-create the tape
device. The system will set the attribute of the tape
device to TAP when creating the new tape device. Be
sure to write down the attributes of the tape device
before deleting. The RST command requires that the tape
device have a TAP attribute.
OS/400 PTF Levels
Web Server/400 and Commerce Server/400 have been tested with
OS/400 cumulative PTF package TC96016 under V3R1 and TC96086
under V3R6. For best results, these packages or later
packages should be applied to your systems.
Additional V3R1 PTFs not included in the cumulative PTF
package listed above should be applied to improve system
stability. Please load the following PTFs on your system.
. The PTFs MF10372, MF10794, MF10795, and MF11235 for the
product 5763999 should be applied. Without these PTFs
the Web server may, in rare circumstances, abend while
calling a system TCP/IP function.
. PTF SF26297 for the product 5763SS1 should be applied
if you use scripts written in Rexx/400. Without this
PTF, performing a SAY with no expression will cause the
Rexx/400 script to cause an exception.
Page 13
Commerce Server/400 1.0 Getting Started
. PTF SF31797 for the product 5763SS1 should be applied
if you use Client Access/400. Without this PTF, the
system will assign a zero code page, which is invalid,
to a file created in IFS when the user's CCSID is not
set to 65535.
Performance Problems Due to Domain Name Server Configuration
Significant performance problems can occur due to an
incorrect configuration of the remote name server (Remote
Host Name Configuration on page 25) within the OS/400
TCP/IP. The remote name server, also known as a Domain Name
Server (DNS), is used by the Web server to query the host
name of a machine requesting a document. If this
configuration specifies a search first parameter of *REMOTE
and the remote DNS does not respond, the Web server will
have to wait for the query to time-out (the number of retry
attempts configured also extends the amount of time the
request waits before failing). If you do not have a DNS
available to you either from your Internet service provider
or internally within your organization, you should leave the
server address blank and specify *LOCAL for the search first
parameter. This should correct your time-out delay, which in
turn will increase the speed of the Web server. The only
other side effect to this configuration change is that the
access log file will contain the IP address of the machine
requesting the document, not the host name.
Problems Starting the Web server Due to Local Host Name
Configuration
The Web Server/400 and Commerce Server/400 products require
a local host name to be set either through the TCP/IP
configuration (Local Host Name Configuration on page 24),
CFGTCP command option 12 (Change local domain and host
names) or through the Web Server/400 server host name
(section 4.13.13 on page 321) configuration value. The error
message displayed on the STRWWW (section 3.2.1 on page 197)
command indicating this error condition is: "The local host
name could not be determined and was not explicitly set."
1.2.1.2 Installation Instructions
If migrating from a previous version, please read the
migration instructions (section 1.1 on page 11) before
continuing with the installation. When upgrading from Web
Server/400 to Commerce Server/400, the Web Server/400's code
is replaced with the Commerce Server/400's code. Installing
Web Server/400 or Commerce Server/400 on the AS/400 requires
the following steps:
1.Sign on the AS/400 as QSECOFR or another user profile
with a user class of *SECOFR. Special authorities are
required to successfully install the server's objects
(Objects Installed on page 15).
Page 14
Commerce Server/400 1.0 Getting Started
2.Run the system command LODRUN to install the server
from the supplied product tape.
Note: Prompt the command to change the tape device if
the default is not appropriate.
The install should take approximately 10 to 30 minutes
depending on the tape device and AS/400 model (NOTE:
RISC AS/400s may take longer if not using a RISC
installation tape due to the extra time it takes to
convert IMPI programs to RISC programs). The install
program displays a message when it is finished
indicating the install was successful.
If any problems occur during the install:
1. Check the joblog to determine the cause of the
error.
2. Correct the problem.
3. Re-run the installation command.
4. If problems persist, please contact support.
1.2.2 Objects Installed
The following objects were created/restored on the AS/400 by
the installation program:
. A user profile named WWWUSER was created. WWWUSER has
no password, a user class of *USER, and no special
authorities. The product user profile WWWUSER owns all
of the objects installed. WWWUSER was also added to the
system directory.
. The product user profile WWWUSER was granted *USE
authority to job queue QSYSNOMAX.
. The product library WWWSERVER was restored. WWWSERVER
contains all of the product code. Product commands, a
message file, menus, and panel groups were copied into
library QSYS. Two utility programs are provided in
library WWWSERVER that can be used to maintain the
product objects that are copied into QSYS:
1. CPYQSYS: Copies product commands, message file,
menus, and panel groups into library QSYS. This
program may be needed after installing a new release
of OS/400.
2. RMVQSYS: Removes product objects from library QSYS.
If the product objects are removed from QSYS, either
WWWSERVER will need to be added to the library list
to access commands and menus or the commands and
menus must be fully-qualified with the product
library. This program needs to be run after each
installation of product code.
Neither program requires any parameters. Both programs
manipulate all I/NET Web product objects (i.e., Web
Server/400, Commerce Server/400 and Webulator/400).
Page 15
Commerce Server/400 1.0 Getting Started
. A product job description named WWWJOBD was created in
library WWWSERVER. The job description was setup to use
the job queue QSYSNOMAX. The product user profile
WWWUSER was changed to use the created job description.
. The library WWWSAMPLES was restored. WWWSAMPLES
contains sample documents that are used to demonstrate
how objects in QSYS are accessed.
. A folder named WEBDOCS was restored. WEBDOCS contains
other folders and documents that are used to
demonstrate accessing objects in QDLS.
. A directory named WWWServ was restored into the root of
the IFS file system. WWWServ contains many other
directories and stream files. WWWServ contains the
following directories:
. Cfg directory contains server configuration files.
The shipped configuration files are saved in a sub-
directory named Shipped.
. Logs directory is the default location of server log
files.
. WebDocs directory is the default server document
root. The Shipped directory off of the WebDocs
directory contains all of the server's publications
and sample content organized in directories. The
/WWWServer/WebDocs/ directory structure is as
follows:
Icons : Sub-directory containing product icons
Shipped : Product sub-directory
/Pubs : Server documentation
/Samples : Sample content
Important note: The server's sample content and
publications will always be shipped in the 'Shipped'
directory. Users should not place content in this
directory for it may be deleted or over-written in
the future.
. WWWUser directory is WWWUSER's home directory.
. Key directory is used by Commerce Server/400 to
store commerce keys.
. Tmp directory is used by Commerce Server/400 for
caching.
. The library WWWCGI was restored. WWWCGI is the default
script library.
Page 16
Commerce Server/400 1.0 Getting Started
1.3 Hardware Configuration
1.3.1 Hardware Requirements
Listed below are the minimum hardware requirements needed to
run Web Server/400. Basically, any AS/400 running V3R1M0 can
run Web Server/400 just fine. The only challenging hardware
configurations involved with Web Server/400 are the TCP/IP
and Internet connections (Network Configurations on page
17).
. Any AS/400 that is supported by OS/400 V3R1M0, V3R2M0,
V3R6M0, or later supports Web Server/400.
. The DASD, RAM, and processor levels chosen depends on
individual capacity and performance requirements.
. Optional: Workstation access to the Integrated File
System and/or Shared Folders through PC Support/400 or
Client Access/400. The creation and management of Web
content is simplified with direct workstation access to
stream files on the AS/400.
1.3.2 Network Configurations
In order for Web Server/400 to be useful, TCP/IP connections
to machines other than the AS/400 running the product must
be available. This is typically done through a Local Area
Network (LAN) or through X.25. The outside machines might be
PCs on the LAN or Internet customers attached to your AS/400
through a TCP/IP router.
Below are the most common network configurations that can be
used by Web Server/400.
1.3.3 Web Server/400 over a LAN
. Local Area Network (LAN)
. Token Ring, Ethernet, or X.25.
. AS/400
. Version 3 Release 1 Mod 0 or later.
. Connected to Token Ring, Ethernet, or X.25 LAN
. TCP/IP
. Web Server/400
. Workstations
. Connected to Token Ring or Ethernet LAN or over X.25
. TCP/IP
. Web browser
Page 17
Commerce Server/400 1.0 Getting Started
. Client Access/400 (for Web content creators and
administrators only) Optional.
1.3.4 Web Server/400 over the Internet - LAN Router
. Local Area Network (LAN)
. Token Ring, Ethernet, or X.25.
. AS/400
. Version 3 Release 1 Mod 0 or later.
. Connected to Token Ring, Ethernet, or X.25 LAN
. TCP/IP
. Web Server/400
. Workstations
. Connected to Token Ring, Ethernet, or X.25 LAN
. TCP/IP
. Web browser
. Client Access/400 (for Web content creators and
administrators only) Optional.
. Internet Access
. Router connected to LAN using Token Ring, Ethernet,
or X.25
. Telecommunication company connection from your
router to access provider
1.3.5 Non-Network Configurations
Currently, Web Server/400 is only useful if a Token Ring,
Ethernet, or X.25 TCP/IP connection is available. A Web
browser for the AS/400 is not available. If one were, then
the content served by Web Server/400 could be accessed
without a network connection.
Also, direct dial-up Internet access is now available on the
AS/400 with V3R2M0 of the OS/400 operating system. However,
since the TCP/IP support on the AS/400 does not support IP
Routing this machine cannot operate as an IP router or
firewall for other machines downstream connected to the
AS/400 through a different network connection (e.g. Token
Ring or Ethernet). The direct dial-up only supports the SLIP
(Serial Line Internet Protocol) protocol (no Point-to-Point
Protocol PPP support). As of this document's publishing, the
fastest line supported by SLIP on the AS/400 is 19.2K
bits/second. The LAN connections discussed earlier in this
document are the recommended means too obtain the peak
performance of your AS/400 and I/NET's Web Server/400 on the
Internet.
Page 18
Commerce Server/400 1.0 Getting Started
1.4 Software Configuration
Web Server/400 works without any changes to the installed
configuration. However, not all features will be available
in this default installation. Listed below are the software
requirements for Web Server/400.
. OS/400 V3R1, V3R2, V3R6 or later. The supported
versions of OS/400 come with all of the TCP/IP
components necessary to run Web Server/400. The
separate product TCP/IP Connectivity Utilities/400 is
not used by Web Server/400, but can be used in
conjunction with Web Server/400.
. TCP/IP connectivity with Web client machines. See
TCP/IP configuration tips for more details. See
Hardware configuration (section 1.3 on page 17) for
network configuration details.
. The latest cumulative PTF package. This is not
necessary but highly recommended. The GA release and
early cumulative PTF packages experienced some problems
when IFS and TCP/IP interacted with each other.
. Optional: Client Access/400 or PC Support/400 (or
equivalent) for workstation access to the Integrated
File System and/or Shared Folders for Web content
creation and server management.
. Optional: Ultimedia System Facilities (section 2.11 on
page 140) (USF) a free option of OS/400 V3R1 or later.
USF can be used to create, store, and manage multimedia
content that can be directly accessed through the Web
browser. USF only needs to be installed if serving Web
content from within the USF multimedia repository is
desired.
Page 19
Commerce Server/400 1.0 Getting Started
1.5 TCP/IP Configuration Tips
This section is intended to give some very basic background
of TCP/IP terminology and some tips on how to configure
TCP/IP on your AS/400 so that you can run the Web Server/400
product. All of the following information refers to TCP/IP
for the V3R1M0 version of the OS/400 operating system.
1.5.1 TCP/IP Terms
Internet Network
An internet network is the term used to describe a
network that contains a collection of machines
communicating together using the internet protocol (IP).
The term Internet with a capital "I" is considered THE
Internet which is the largest implementation of a network
running the internet protocol. All references to an
internet network using a lower case "i" refers to a local
network which may or may not be connected to the
Internet.
Host
The term host is used to describe any machine with an IP
address participating on an internet network. This
includes workstations and machines running OS/400.
Internet Protocol (IP) Address
A 32 bit number broken up into 4 bytes (each 8 bits in
size). The number will be represented as a decimal number
with a "." separating each of the 4 bytes. In the decimal
notation each of the four numbers can contain a value
between 0 and 255. The values 0 and 255 are considered
special values (broadcast and loopback) and should not be
used when determining a host's IP Address. All machines
on an internet network must have a unique IP address. IP
addresses include a network and host portion. The network
portion is used to determine which network the host
resides on, and the host portion is used to uniquely
identify the machine within that internet network. This
concept can get complicated, especially if subnetting is
taking place within your network.
Gateway or Router
A machine that is used to bridge two internet networks
together. This is needed when you want to send/receive
information outside of your local network. For example,
if your AS/400 is going to be connected to the Internet
you will need a router to connect your local network to
one of the Internet backbone networks (or to a network
Page 20
Commerce Server/400 1.0 Getting Started
which is connected through other networks to one of the
Internet backbone networks).
Route
A route is used to determine the IP address of a gateway.
A route is not needed for information which is being sent
to or received from machines which reside on the same
internet network.
Subnet Mask
The subnet mask is used to determine what bits of the IP
Address are used to assign the network portion. Any bits
within the subnet mask that are set to 1 are used to
determine the network. You will need additional
information beyond this documentation if you intend to
set up sub-networks within your internet network.
However, we should note that the subnet mask is needed to
configure TCP/IP on the AS/400 and further discussion
will take place to assist you in setting this value.
Ping
A TCP/IP utility which sends test information and waits
for the information to return. The utility displays the
amount of data sent and received and the amount of time
elapsed while doing so. The utility is very useful when
testing the TCP/IP configuration. "Ping" is the name of
the command. It accepts one parameter, the IP address or
host name of the remote system to send/receive the data.
1.5.2 Assigning your AS/400 an IP Address
If you plan on placing your Web Server on the Internet, you
will need to discuss the assignment of the network portion
of your IP address with your Internet access provider. If
you are not planning on placing your AS/400 on the Internet
or your Internet access provider does not currently have a
permanent IP address for you, then you are not restricted to
the address you want to use. However, as soon as your
internet network connects to other internet networks your
network's IP addresses must be unique throughout all of the
networks connected.
This value can be reconfigured at a later point if you want
to the AS/400 to be accessible on the Internet and you don't
currently have an Internet access provider or your provider
does not have a permanent address that they can assign to
you immediately. Note: all hosts on the same network require
the same network portion of the IP address and only the host
portion of the IP address will be unique per machine.
Page 21
Commerce Server/400 1.0 Getting Started
1.5.2.1 Assigning the network portion of an IP Address
In the case where the network portion of your IP address has
not been assigned to you by a network administrator or an
Internet access provider, you can use this section to better
understand the network portion and assign one yourself.
The most typical type of network address is a class 'C'
address. A class 'C' address begins with the first byte
having a value in the range of 192 to 223. For our example
we will choose 200 for the first portion of the network
address, which indicates that we are assigning a class 'C'
address and that we expect to have less than 254 machines on
our internet network. For the rest of the network portion we
will choose values of 1. Therefore, we will use the address
"200.1.1" as the network portion of our IP address.
1.5.2.2 Assigning the host portion of an IP Address
For our discussion we are assuming that the network portion
was defined to be a class 'C' address with no subnetworks
defined. With a class 'C' address the last byte will be used
for the host portion allowing the address of 1 - 254 to be
used for these values. It would make sense for the
administrator of this internet network to make all of the
host portion assignments and to track these values in order
to ensure that each machine is assigned a unique ID.
1.5.3 Working with the OS/400 commands to configure TCP/IP
This section of the Web Server/400 documentation will assist
the user in configuring the minimum TCP/IP features
necessary to run the Web Server/400 product.
The user must signon as QSECOFR or have equivalent
authorities in order to be able to use the following
commands effectively. Some of the commands will let you view
the information but not change it if you do not have these
authorities.
The CFGTCP is an OS/400 command which gives the user a list
of options available to configure the TCP/IP interface.
Select the Work with TCP/IP interfaces option 1. The user
will be presented with a screen that shows the current
interfaces configured. An interface as it is presented on
this screen refers to the line supporting the TCP/IP
protocol and the IP address associated with that line. The
*LOOPBACK line is a special line and is required for TCP/IP
to operate properly.
To add an interface use option 1 (also available directly as
the ADDTCPIFC command). The three required parameters are:
Page 22
Commerce Server/400 1.0 Getting Started
Internet address
The value required for this parameter is the IP address
chosen for this AS/400. If the machine is acting as a
gateway and has multiple lines being configured to
support TCP/IP then this value is the IP address set for
the line being configured.
Line description
V3R1 OS/400 TCP/IP does not support all types of line
descriptions. Refer to the help information available
from this parameter within the ADDTCPIFC command for
detailed information about what line descriptions are
supported. The typical line descriptions used when
configuring a TCP/IP connection for use with the Web
Server/400 product would include a permanent connection
such as Token Ring or Ethernet LAN connections. This
would allow the Web Server/400 product to be available 24
hours a day 7 days a week without incurring additional
usage costs. If the Web Server/400 product were to be
made available through an Internet connection then either
the Token Ring or Ethernet connection could be used along
with a router connected to a leased line. The leased line
would be permanently connected to the Internet access
provider and available 24 hours a day 7 days a week at a
fixed rate.
Subnet mask
Set this value to 255.255.255.0 for a class 'C' address
which has no subnetworks defined. For any other type of
scenarios additional research will be required. Refer to
the TCP/IP terms (Subnet Mask on page 21) section above
for a basic definition of subnet mask.
The other parameters should not require any changes for the
basic setup. If you are just getting started or are not
connected to any other internet networks then the OS/400
side of things are all up and running ready and are ready to
be used.
If you have an Internet connection or a connection with
other internet networks, you will need to configure a route
to the gateway for data to flow between these internet
networks. The CFGTCP command option 2 Work with TCP/IP
routes provides a list of already configured routes. Within
this option you have the ability to add routes. You will
want to add a default route that is used for all traffic
that is not destined for the internet network that the
AS/400 resides on (machines that contain a different IP
Address network portion other than that set for this AS/400
machine). Choose option 1 (also available directly as the
ADDTCPRTE command) to add the default route. The three
required parameters are:
Page 23
Commerce Server/400 1.0 Getting Started
Route destination
"*DFTROUTE" is the keyword used to indicate the default
route.
Subnet mask
"*NONE" is the only valid value to specify for a default
route.
Next hop
The IP address of the gateway (router) should be
specified for the next hop parameter. This indicates that
for the default route all of the information being sent
out should next go the gateway machine. From there the
gateway machine will use its routing tables to determine
where to send the information.
1.5.4 Starting and Testing your TCP/IP Configuration
The STRTCP command is used to start the TCP/IP services on
the AS/400. After the TCP/IP services have been configured
and started, you will want to test the configuration. The
PING command is a good way to test the local and remote
TCP/IP configurations.
First use the PING command to test the local configuration
by specifying the AS/400's IP address for the Remote system
parameter. Check the results of the PING command by looking
at the job log. If the job log shows that 100% of the
packets sent were received successfully then the
configuration on the AS/400 was a success.
After verifying the local configuration the remote
configurations can be tested. In order to test any remote
configurations you need to have another machine configured
and running TCP/IP on your internet network (your gateway is
a good test if you have one configured and running). Use the
PING command again this time specifying the remote system IP
address or host name. Again check to ensure that 100% of the
packets were successfully sent and received.
1.5.5 Host Names
1.5.5.1 Local Host Name Configuration
Up to this point we have discussed the host machines by
referencing them using a unique IP address. A second way to
reference the host machines is to assign them a host name. A
host name is an alternate meaningful name assigned to a
host. For example, the host name of www.inetmi.com refers to
the web server I/NET, Inc. is running to demonstrate the Web
Server/400 product. The www portion of that name is the host
Page 24
Commerce Server/400 1.0 Getting Started
portion the inetmi.com portion is the domain name. The local
host and domain name can be set using option 12 (Change
local domain and host names). If you are planning on
connecting to the Internet you should discuss registering a
domain name for your internet network with your Internet
access provider.
Problems Starting the Web Server/400 Due to Local Host Name
Configuration
The Web Server/400 product requires a local host name to be
set either through the TCP/IP configuration, CFGTCP command
option 12 (Change local domain and host names) or through
the Web Server/400 server host name (section 4.13.13 on page
321) configuration value. The error message displayed on the
STRWWW (section 3.2.1 on page 197) command indicating this
error condition is: "The local host name could not be
determined and was not explicitly set."
1.5.5.2 Remote Host Name Configuration
The CFGTCP command provides multiple ways to assign remote
host names. The first way would be to update the local host
table using option 10 (Work with TCP/IP host table entries)
(this would allow you to map the IP address of the remote
machine to a meaningful name). The drawback to doing it this
way is that if you have a lot of machines that you would
like to reference by name, you have to add them all to this
table. A second way of configuring names would be to
reference a remote host running the TCP/IP Domain Name
Service (DNS) using option 13 (Change remote name server).
By using a DNS server hosts can be added to your network
with meaningful names without any additional configuration
required to remote machines. V3R1 OS/400 TCP/IP does NOT
include a the ability to act as a DNS.
Performance Problems Due to Remote Name Server Configuration
Significant performance problems can occur due to an
incorrect configuration of the remote name server within the
OS/400 TCP/IP. The remote name server, also known as a
Domain Name Server (DNS), is used by the Web Server/400
product to query the host name of a machine requesting a
document. If this configuration specifies a search first
parameter of *REMOTE and the remote DNS does not respond,
the Web server will have to wait for the query to time-out
(the number of retry attempts configured also extends the
amount of time the request waits before failing). If you do
not have a DNS available to you either from your Internet
service provider or internally within your organization, you
should leave the server address blank and specify *LOCAL for
the search first parameter. This should correct your time-
out delay, which in turn will increase the speed of the Web
server. The only other side effect to this configuration
change is that the access log (section 2.16.4 on page 166)
Page 25
Commerce Server/400 1.0 Getting Started
file will contain the IP address of the machine requesting
the document, not the host name.
For additional information concerning the configuration of
TCP/IP the user can reference the V3R1 OS/400 publications
or the information provided online by the IBM Corporation.
Page 26
Commerce Server/400 1.0 Getting Started
1.6 Starting the Server
1.6.1 Starting Web Server/400 or Commerce Server/400
The following steps should be followed to start Web
Server/400. Note that these instructions also apply to
starting Commerce Server/400 without support for secured
transactions (additional steps (section 1.10 on page 34) are
required to enable Commerce Server/400 to perform secured
transactions).
1.Sign on the AS/400 with a user profile that has *ALLOBJ
authority (e.g., QSECOFR).
2.Once TCP/IP has been configured on the AS/400, start
TCP/IP support using the STRTCP command (if not already
started).
3.Start the Web Server using the STRWWW (section 3.2.1 on
page 197) command, which is accessible through the
CMDWWW (Menus on page 196) menu. When starting the
server for the first time perform the following steps:
1. Prompt the STRWWW command
2. Press enter (use the default master configuration
file)
3. Press F10 to view additional parameters
4. Key in the product activation key provided to you by
your supplier with the product tape and press enter.
Contact your supplier if you did not receive an
activation code or your activation code does not
work.
If the server does not start due to an error:
1. Check the joblog to determine the cause of the
error.
2. Correct the problem.
3. Re-run the STRWWW command.
4. If problems persist, please contact support.
Once the server is started, Web browsers can connect to the
server and peruse the online publications and sample
documents. The server can be stopped using the ENDWWW
(section 3.2.2 on page 202) command.
1.6.2 Accessing the Server
Start a Web browser on the workstation. In the Web browser's
current URL edit field enter the following URL:
http://server/
where,
server is the fully qualified domain name of the
AS/400. The server may be identified with an internet
address (e.g., 200.0.0.1) or a configured host name for
Page 27
Commerce Server/400 1.0 Getting Started
the AS/400's internet address. See the person
responsible for AS/400 TCP/IP configuration for the
proper value.
Processing this URL will return the Web Server/400's home
page. From the home page the online pubs can be viewed to
learn more about the Web Server/400 product. When using the
default configuration, Commerce Server/400 acts just like
Web Server/400. The above instructions will allow you to
view online content unsecurely. Further steps (section 1.10
on page 34) are required to make Commerce Server/400 serve
pages securely.
Page 28
Commerce Server/400 1.0 Getting Started
1.7 Viewing Web Server/400 Documentation from a Browser
All of the documentation is written in HTML (Hyper Text
Markup Language) which will allow you to view it through a
web browser in one of two ways:
1.7.1 Accessing Document Files Directly
Connect to the AS/400 through a network drive and use a web
browser which is written to work with Microsoft Windows 3.1
or OS/2.
Upon installation, the Web Server/400 user guide
documentation is located in the directory
/WWWServ/WebDocs/Shipped/Pubs. Most web browsers have the
ability to load and view HTML marked up files directly from
a disk. Therefore, if your browser has this ability you can
load the files through this means.
The Client Access/400 for Windows 3.1 or Client Access/400
Optimized for OS/2 software packages allows you to connect
to the IFS Root file system through a network drive
definition. In order to reach the drive necessary you can
either connect a drive directly to the
/WWWServ/WebDocs/Shipped/Pubs directory or you can connect
to the ROOT of the IFS file system and work your way through
the path (/WWWServ/WebDocs/Shipped/Pubs) to reach the
documentation.
Since the documentation is an HTML marked up document there
are many files which make up the entire documentation. The
base document is named usrguide.htm. Access this file to
start at the beginning of the document.
1.7.2 Accessing Documentation through Web Server/400
Once the Web Server/400 product is started, the
documentation is available through the server. Upon
installation, the Web Server/400 user guide documentation is
located in the directory /WWWServ/WebDocs/Shipped/Pubs . If
the Web Server/400 product is started with the shipped
configuration the documentation can be accessed through the
Web Server/400 product using the following URLs:
/Shipped/pubs/ or /Shipped/pubs/usrguide.htm
Page 29
Commerce Server/400 1.0 Getting Started
1.8 Testing the Setup
The following is a list of tests which will help you
determine if the server has been configured properly for
access. The intention of the list is to check the basic
areas of access and should not be considered to be a
comprehensive set of tests. These tests also apply to
Commerce Server/400 running as a regular HTTP server (i.e.,
not serving documents securely using SSL). Additional test
cases (section 1.10 on page 34) are available for testing a
site protected using SSL.
In order to perform the following tests the server must be
started on the AS/400 and a Web browser must be running on
the workstation.
Access to the IFS document root directory.
The document root for the IFS file system is set to
WWWServ/WebDocs in the default configuration. Attempt to
access the URL http://your.system.name/ (/) substituting
your AS/400 system's host name or IP address for the
your.system.name part of the URL. The home page shipped
with the Web Server/400 product should be displayed. The
actual file brought back to the browser should be the
index.htm file found in the WWWServ/WebDocs directory.
Access the Web Server/400 User's Guide.
The following URL should display the Web Server/400
User's Guide
http://your.system.name/shipped/pubs/usrguide.htm
(/shipped/pubs/usrguide.htm).
Access to the QDLS file system.
Attempt to access the http://your.system.name/QDLS/
(/QDLS/) URL substituting your AS/400 system's host name
or IP address for the your.system.name part of the URL.
This should bring up the Dynamic Indexing view of the
directory /qdls/ found on your system. QDLS has been
configured as an alias (section 2.4 on page 65) pointing
to the /QDLS/ directory. See the URL Locations (section
2.3 on page 53) section for further explanation about why
an alias is needed to access the /QDLS/ directory when
the default source type is not set to *QDLS. The
resultant dynamic index should contain a Samples/
directory which, if clicked on, should contain other
sample file(s) to view.
Access to the QSYS and QSYS/WWWSAMPLES library.
Attempt to access the http://your.system.name/QSYS/
(/QSYS/) URL substituting your AS/400 system's host name
or IP address for the your.system.name part of the URL.
Page 30
Commerce Server/400 1.0 Getting Started
This should result in a forbidden message indicating that
the server is not configured to allow access to the QSYS
library. Attempt to access the
http://your.system.name/QSYS/WWWSAMPLES.LIB/ URL. This
should bring up the a Dynamic Indexing (section 2.14 on
page 144) view of the library WWWSAMPLES restored on your
system through the Web Server/400 install. The dynamic
index should show multiple files residing within the
library. Both of the QSYS examples used the QSYS alias.
See the URL Locations (section 2.3 on page 53) section
for further explanation about why an alias is needed to
access the QSYS directory when the default source type
(section 4.13.3 on page 311) is not set to *QSYS. Also
see the include libraries (section 4.9.1 on page 292)
configuration section to determine how to allow access to
other libraries.
View server log files.
Once the server has been ended with the ENDWWW (section
3.2.2 on page 202) command, there are 3 log files that
could be available for viewing: the access log, the
statistics log (section 2.16.5 on page 170), and the
error log (section 2.16.6 on page 176). The error log
file will not exist in the case where no errors were
logged. The default directory for these logs is the
/WWWServ/Logs/.
Page 31
Commerce Server/400 1.0 Getting Started
1.9 Where to Go from Here
Now that the product is installed and running, it is time to
find out more about what can be done with the Web Server/400
product. This page suggests some of the more important
sections to read and some of the changes that have been made
to the product since version 1.2.
Below are some useful sections to read before going much
further with Web Server/400.
. What is a Web Server? (section 2.1 on page 44)
. URL Locations (section 2.3 on page 53)
. Aliases (section 2.4 on page 65)
. Logs (section 2.16 on page 163)
. Commands (section 3.1 on page 194)
. Configuration Values (section 4.1 on page 239)
1.9.1 New since Web Server/400 Version 1.2
Natonal Language Support
Support for serving double- and mixed-byte content has
now been included in the product.
IFS File CCSID Override Abilities (section 4.13.6 on page
314)
Support for mixed byte files and the ability to override
incorrect IFS code pages is now included.
Authentication User Storage (section 2.15.5 on page 154)
Previous versions of Web Server/400 allowed for the
storage of authentication user information in stream
files. You can now choose to store users in stream files
or database files (for authentication only, not for
Webulator/400).
The way that user passwords are stored (for
authentication only, not for Webulator/400) has also
changed since the availability of Web Server/400 version
1.2. The Web Server can be configured to use the new
Normalized mode of password encoding.
Server Identification Support (section 4.13.14 on page 322)
Used to identify and describe a server. The server
identifier is used in the naming of the server jobs
(Server Jobs on page 200) and objects, and is supported
by the server start and end commands (Operational
Commands on page 194).
Page 32
Commerce Server/400 1.0 Getting Started
Server Start and End Command Enhancements.
Used particularly during the start of operations for an
AS/400, or for the start of TCP/IP operations, the STRWWW
command (section 3.2.1 on page 197) now has enhanced
functionality that waits for TCP/IP to be active before
beginning server activity.
In addition, it is now possible to end all Web Server/400
activity via the ENDWWW command (section 3.2.2 on page
202).
Server Performance
Many enhancements have been included to achieve improved
performance by incorporating more efficient processes and
calls to system functions. Server performance (Server
Performance on page 202) can be affected by many factors.
Advanced configuration (Advanced Configuration on page
202) provides information that can be used to customize
how the server runs on your system.
Page 33
Commerce Server/400 1.0 Getting Started
1.10 Setting Up Commerce Server/400
NOTE:
The discussion contained here is only applicable to
owners of Commerce Server/400. Web Server/400 owners
cannot perform secured transactions.
1.10.1 Overview
With the unmodified, default configuration files shipped
with Commerce Server/400, the server runs the same as Web
Server/400. That is, by default, the server does not do
secured transactions. Below are the steps that need to be
accomplished before secured transactions can be performed.
Please read through all the instructions presented here
before proceeding.
1.Install (section 1.2 on page 13) Commerce Server/400.
2.Obtain a Server Certificate.
1. Enroll with the Certification Authority
2. Create a Public Key, Private Key, and a certificate
request.
3. Submit the certificate request to a Certification
Authority.
4. Install certificate received from the Certification
Authority.
3.Change Commerce Server/400 Configuration Values.
1. Set the Keylist Database File.
2. Set the Protocols configuration value to SSL.
3. Set the Allowed Protocols directory based
configuration value to SSL for the root directory.
4.Start the server (or re-start a running server).
1.10.2 Obtaining a Server Certificate
This step is the most time consuming step since it requires
interacting with a new entity: a Certification Authority
(CA). Customer's of Commerce Server/400 are able to easily
obtain server certificates from the Certification Authority
VeriSign, Inc. (http://www.verisign.com/) VeriSign, Inc.
supplies server certificates (or Digital IDs ) for a variety
of security enhanced products. You will become a customer of
VeriSign once you purchase a server certificate from them.
VeriSign will also assist you with any special needs you may
have concerning your server certificate. Below are sources
of additional information about VeriSign and server
certificates:
Page 34
Commerce Server/400 1.0 Getting Started
. Introduction to Cryptography
(http://www.verisign.com/docs/pk_intro.html)
. Frequently Asked Questions (Digital IDs)
(http://digitalid.verisign.com/id_faqs.htm)
. Frequently Asked Questions (Server Digital IDs)
(http://www.verisign.com/faqs/cert_faq.html)
. General Cryptography FAQ
(http://www.rsa.com/rsalabs/faq) from RSA Data
Security, Inc.
. VeriSign's Price Schedule
. Additional instructions for international (non-
US/Canadian) customers or Japanese customers
Server certificates are required for Commerce Server/400 to
serve secure documents. The certificate will provide proof
to your site's visitors that they are indeed communicating
with your company, and it will provide browsers with your
company's public key. This public key allows secure
communications to be initiated between your server and your
visitor's browsers.
VeriSign provides an enrollment process that must be
followed to receive a certificate. This allows VeriSign to
validate your identity to ensure some other entity is not
masquerading as your company. The entire process may take
several days to complete and you cannot perform secure (SSL)
transactions until everything is finished.
1.10.2.1 VeriSign Enrollment
VeriSign provides an on-line enrollment process. To obtain a
server certificate for Commerce Server/400 from VeriSign, go
to the URL http://www.verisign.com/inet
(http://www.verisign.com/inet). To do this, you will need a
browser that is attached to the Internet and capable of
performing SSL requests. The above page will provide
introductory information about the enrollment process. After
reading this information, select the Begin button.
The Enrollment Form will be displayed. Carefully read and
follow the instructions provided on this page. You will be
asked to supply information on your distinguished name, your
company, payment information, and contacts. Submit this form
using the Continue button. The server will return an error
page if anything was missing or not entered correctly. If
you receive errors, follow the instructions to fix them.
Page 35
Commerce Server/400 1.0 Getting Started
1.10.2.2 VeriSign Authorization Letter
Continuing with the VeriSign enrollment process, the
VeriSign Secure Server Authorization Letter page should be
displayed on your browser. You must fill in this form and
acknowledge its contents before proceeding.
1.10.2.3 Creating a Public Key, Private Key, and Certificate
Request
The next stage in the enrollment process is to generate a
certificate request. Here are some specific instructions for
generating a server certificate for Commerce Server/400, in
addition to the instructions listed on the Generate a
Request page.
The keylist database file and certificate request file are
created by running the command CRTWWWKEY. Please follow the
instructions for CRTWWWKEY when running this command.
CRTWWWKEY will produce a keylist database file and a
certificate request file. The certificate request file will
be given to the Certification Authority to produce your
server certificate. By default, this file is put in the
document root of the Web server. This makes it easy to cut
and paste the contents into an HTML form or an e-mail
message (see below).
The keylist database file contains your public and private
keys. These are used by the server to perform encryption and
digital signing tasks. The keylist database file is
encrypted using the password you provide.
WARNING: The keys are randomly generated and cannot be re-
created if the file is lost or if the password is forgotten.
If you lose access to this file, you must obtain a new
certificate from VeriSign (for an additional fee) by
repeating all of these instructions.
IMPORTANT: The distinguished name entered into the CRTWWWKEY
command must be exactly the same as the distinguished name
entered in the VeriSign Enrollment Form. If possible, copy
and paste this information from the VeriSign Authorization
Letter into the command. You can use your browser's Back
button to see the letter again. If this information is
different in any way, the request will be rejected by
VeriSign.
1.10.2.4 Submitting the Certificate Request
Once the CRTWWWKEY command has successfully completed, a
certificate request stream file will exist. The contents of
this stream need to be e-mailed to VeriSign. The
instructions below go through one way of e-mailing this
information to VeriSign. These instructions assume that you
Page 36
Commerce Server/400 1.0 Getting Started
have Internet e-mail capabilities and Web browsing
capabilities on the same machine.
Step 1
From your browser, load the certificate request file
generated using the CRTWWWKEY command. If you are using
the defaults, you can load the URL:
http://www.yourhost.com/certrqs.txt into your browser.
Copy the entire page into your clipboard. Note: Your Web
server needs to be running to access this file.
Alternatively, you can load the certificate request file
into a text editor and copy the contents into your
clipboard from the text editor. If you have a drive
assigned to the root file system of IFS and you are using
the defaults for CRTWWWKEY and for the Web server, you
can open the file /wwwserv/webdocs/certrqs.txt. If you
only have shared folders access, have the CRTWWWKEY
command write the certificate request file to a document
in shared folders then load that document into a text
editor.
Step 2
Create a new Internet e-mail message addressed to inet-
request-id@verisign.com
Step 3
Paste the certificate request generated by CRTWWWKEY into
the body of the e-mail message.
Step 4
Send the message.
1.10.2.5 Installing the Certificate
After you receive your certificate from VeriSign through e-
mail, you are ready to install the certificate into Commerce
Server/400. This is done by running the AS/400 command
ADDWWWCERT (section 3.4.1.3 on page 234).
Step 1
The e-mail message that contains your certificate needs
to be saved in a stream file in the root file system of
IFS or in QDLS (shared folders). If you have a drive
connected to your AS/400 from your e-mail machine, save
the message to a file directly on the AS/400. Otherwise,
you can use FTP to transfer the file from your e-mail
machine into QDLS on your AS/400.
Step 2
Run the ADDWWWCERT command specifying the file created in
Step 1 as the Signed Certificate File. For example, if
you used FTP to get the file into QDLS on the AS/400 you
may use a filename like /qdls/myfolder/cert.txt. Provide
Page 37
Commerce Server/400 1.0 Getting Started
the same password and keylist file that was supplied to
the CRTWWWKEY command that generated the certificate
request file for this certificate. Usually a PKCS10
formatted certificate is returned.
You should now have a valid and usable keylist database
file. Prior to this, trying to start Commerce Server/400 in
a secure mode using this keylist file would fail. The
keylist file needs both the public and private keys and the
associated certificate to be valid.
1.10.3 Enabling Commerce Server/400 to do SSL
The following three configuration values need to be changed
in order to enable secure transactions through Commerce
Server/400. After making these changes, all pages served by
Commerce Server/400 will be encrypted. You may want to set
up (HTTP and SSL on page 48) Commerce Server/400 to serve
some content encrypted and some content unencrypted. You can
also start two instances of Commerce Server/400 (combined on
page 49); one that handles regular HTTP requests and one
that handles SSL requests.
1.10.3.1 Set the Keylist Database File
Using the command CHGWWWSEC (section 3.4.1.1 on page 230),
the keylist database file can be set to the newly completed
keylist file. By default this would be
/WWWServ/Key/KeyList.Cfg. The other values can be left to
their default values.
1.10.3.2 Set the Protocols Value
Using the command CHGWWWCFG (section 3.3.1 on page 207), the
Protocols configuration value can be changed from HTTP to
SSL.
1.10.3.3 Set the Allowed Protocols Value
Commerce Server/400 has a new Directory Based Configuration
value: Allowed Protocols (section 4.13.1 on page 310). This
tells Commerce Server/400 which protocol (SSL or HTTP)
should be used to serve documents out of a directory and its
subdirectories. This value should be set to SSL in the root
directory so all documents served off of your AS/400 are
served using SSL.
Using the CHGWWWCFG (section 3.3.1 on page 207) command, set
the Directory Based Configuration file (ACCGBLFILE) to
/wwwserv/cfg/access.cfg. If this value is already set to
your own configuration file, you don't need to do this.
Page 38
Commerce Server/400 1.0 Getting Started
Using the WRKWWWDIR (section 3.3.29 on page 224) command,
add the directory "/" using option 1 (Add). If this
directory is already present, you don't need to add it.
Select option 14 (Change Commerce Server/400) on the "/"
directory. Select SSL as the Allowed Protocols and make sure
HTTP is not selected.
1.10.4 Start the Server
The server should now be ready to start, using the STRWWW
(section 3.2.1 on page 197) command. If the server is
already running, you must end the server and re-start it to
enable secure transactions. SSL cannot be enabled by
reconfiguring the server since a password is now required.
You must provide the Keylist Database File password on the
STRWWW command now that SSL transactions are being handled.
To access this server from your browser, you need to use the
protocol identifier https instead of http. For instance, to
open a new URL from your browser enter
https://www.yourhost.com/.
1.10.5 Testing the Server
The following information can help test whether documents
are being served securely (encrypted and authenticated) by
Commerce Server/400.
Accessing a page secured with SSL
From your browser, enter the following URL into the Open
Document or Open URL entry box. This will bring down the
Web site's home page securely.
https://www.your.host.com/
The protocol to use is https for SSL pages. Substitute
your host name for the www.your.host.com portion of the
URL.
When accessing pages from a server running a certificate
from an untrusted Certification Authority (such as
Northern Telecom's Entrust Demo Web Certification
Authority), the browser will usually put up a dialog box
indicating that the server's certificate could not be
verified. Some browser's will let you continue after
answering some questions. Netscape version 2.0, for
instance, will display a series of dialog boxes
explaining that the server's certificate could not be
validated. These dialog boxes are not present if the
server certificate is obtained from a Certification
Authority that the browser trusts (such as VeriSign,
Inc.).
Page 39
Commerce Server/400 1.0 Getting Started
How do I know my pages are secured?
All SSL-enabled browsers provide a visual clue that the
current page is protected using SSL. The clue is usually
a picture of a key or a lock near the bottom of the
browser's window. Also, most browsers have a menu option
that allows you to view information about the server's
certificate.
Browser Support
Only browsers that are enabled with SSL 2.0 or 3.0
support can be used to do secured transactions with
Commerce Server/400. Known, popular browsers that work
with Commerce Server/400:
. Netscape Navigator version 1.1N, 2.x, or 3.0
. Microsoft Internet Explorer 2.0 or 3.0
. OS/2 Secure Web Explorer 1.0 or later.
1.10.6 Test and Evaluation Server Certificates
If you are not running a production Web site yet and want to
try out Commerce Server/400 without purchasing a validated
certificate from VeriSign, or if you would like to start
evaluating the software while you wait for your official
server certificate, you can follow these instructions to
obtain a test and evaluation server certificate.
Northern Telecom provides free test and evaulation
certificates for anyone that agrees to their terms. These
are available from Northern Telecom's Web site through their
service entitled Entrust Demo Web Certification Authority.
Note: The Entrust Demo Web Certification Authority service
is provided and supported by Northern Telecom. This service
is currently available and works with Commerce Server/400.
However, I/NET makes no claims that this service will always
be available or appropriate for Commerce Server/400
customers. It is up to Northern Telecom to continue this
service.
Important: The certificate obtained from Northern Telecom
should only be used for test and demonstration purposes and
cannot be used for commercial purposes. Northern Telecom
does not verify the identity or credentials of the
certificate requester before issuing the certificate. This
service is only meant to provide a quick, easy, and
inexpensive way of obtaining demo server certificates.
Please read the acknowledgement page on Northern Telecom's
site and remember to include their disclaimer page on your
Web site.
Note: If any of the www.nortel.com hyperlinks in this
document are no longer valid, they can be found off of the
Page 40
Commerce Server/400 1.0 Getting Started
page http://www.nortel.com/entrust
(http://www.nortel.com/entrust).
1.10.6.1 Creating a Public Key, Private Key, and Certificate
Request
Follow the instructions given above (Creating a Public Key,
Private Key, and Certificate Request on page 36) for
creating a public and private key and certificate request
for VeriSign.
1.10.6.2 Submitting the Certificate Request
Once the CRTWWWKEY command has successfully completed, you
can submit your request for a test server certificate to
Northern Telecom's Entrust Demo Web Certification Authority
Web site.
Step 1
From your browser, load the certificate request file
generated using the CRTWWWKEY command. If you are using
the defaults, you can load the URL:
http://www.yourhost.com/certrqs.txt into your browser.
Copy the entire page into your clipboard. Note: Your Web
server needs to be running to access this file.
Step 2
Load Northern Telecom's Entrust Demo Web CA page into
your browser:
http://www.nortel.com/entprods/entrust/certificates/servc
ert.html. You need to have Internet access from your
browser to do this.
Step 3
Select the "Proceed with a request" link. Read their
acknowledgement page carefully. If you agree, select the
"Acknowledged" link.
Step 4
Fill in the entry fields on the form. Be sure to supply
an accurate Internet e-mail address since this is how you
will receive your certificate.
Step 5
Paste your certificate request obtained in Step 1 into
the Encoded Certificate Request entry field on the form.
Step 6
If everything looks right, select the "Submit Request"
button.
Your certificate will be automatically sent to you by e-
mail. This usually takes just a few minutes. If you submit
Page 41
Commerce Server/400 1.0 Getting Started
the request on a weekend or holiday, the certificate may not
arrive until the next business day.
1.10.6.3 Installing the Certificate
Follow the instructions given above (Installing the
Certificate on page 37) for installing a certificate
received from VeriSign.
When you receive your real server certificate, simply change
the keylist database file you are using for your server
(using the CHGWWWSEC command) to the new keylist database
file and re-start the server.
Page 42
Commerce Server/400 2.0 Using Commerce Server/400
2. Using Commerce Server/400
Page 43
Commerce Server/400 2.0 Using Commerce Server/400
2.1 What is a Web Server?
2.1.1 Introduction
TCP/IP, Internet, World Wide Web, Browsers, HTTP, HTML.
Where does Web Server/400 fit with all these new terms
flooding the corporate and private world? First take a look
at the general meanings of these terms.
TCP/IP
A protocol used to carry data over a local or wide area
network.
Internet
The name given to the now immensely popular, world-wide
collection of networks-most of which are running TCP/IP.
World Wide Web
The term used to describe a collection of cooperating
protocols that ride on top of the Internet and make it
more accessible and powerful.
Browsers
The very visible end-user tool used to view the material
that is available on the World Wide Web.
HTTP
The protocol (Hypertext Transfer Protocol) that allows
Web browsers and Web servers to communicate over the
World Wide Web.
HTML
The standard markup language (Hypertext Markup Language)
that allows Web browsers to display the rich and user-
friendly information stored on the World Wide Web.
2.1.2 A Web Server's Role
A Web server is the caretaker of all the information that
travels over the World Wide Web (WWW) to the Web browsers. A
person interested in surfing the WWW would start up a
browser and specify a place to start looking. Most all the
information received while surfing comes from a Web server.
A Web server is responsible for managing and delivering the
content that an organization wishes to make available over
the WWW. The Web server takes a large repository of
information and makes it easily available to whomever wants
to view it. This information can be in an almost endless
number of different shapes, forms, and sizes. The most
Page 44
Commerce Server/400 2.0 Using Commerce Server/400
popular of which include HTML, text, images, audios, and
movies.
2.1.3 Who Deals with a Web Server?
Who sees the Web server? Most users of the WWW never really
see a Web server. Their view of the Web is the browser tool
they are using and the information they obtain. The server
end of the WWW is mostly seen by the person(s) that
administers the Web server and the people that are
responsible for providing the content for a Web site.
2.1.3.1 Administrators
Every Web site will have one or more administrators of the
Web server. Whether this is an official position or an
informal one, at least one person will perform
administrative tasks on the server. A popular title for
people in this position is Webmaster.
The administrator is responsible for installing the Web
server, doing initial configuration, performing on-going
configuration, monitoring the accesses to the server,
monitoring errors, organizing at a high level where the
content is stored, answering questions from end-users, and
ensuring that the security and integrity of the machine is
not compromised. These tasks are in addition to normal
service tasks like backing up data, ensuring the machine is
operating correctly, and ensuring that it is accessible.
2.1.3.2 Content Creators
Making sure the Web server is running correctly and that it
can be accessed by end-users, doesn't mean much if the
server doesn't have anything to serve. The content creators
are responsible for providing the information that the Web
server will provide.
Generally, this task is handled by many different people.
Content creators may be from the company's marketing
department, graphic arts department, technical staff,
project management, or individual employees. Many times,
talents from all of these areas need to be combined in order
to create the best content.
Content creators are responsible for deciding what goes on
the Web server, creating the artwork, creating the HTML
documents, organizing the information, making the content
homogenous, keeping the content up-to-date, integrating
existing or outside data with the Web server, and writing
programs (scripts) that interact with browsers.
Page 45
Commerce Server/400 2.0 Using Commerce Server/400
Notice that the descriptions of the administrators and
content creators are quite different. It may not be easy to
find one individual (or a set of individuals) that is well
suited for both tasks.
2.1.4 Hypertext Transfer Protocol Basics
You don't need to understand anything about the Hypertext
Transfer Protocol (HTTP) in order to administer a server or
create content for it. But knowing a little can be helpful
to the administrator and essential for the more advanced
content creator.
On the WWW, a browser always initiates a conversation with a
Web server. This happens every time someone clicks on a
hyperlink in an HTML document or opens a new Uniform
Resource Locator (Uniform Resource Locator on page 53)
(URL). From the URL, the browser can determine which Web
server to talk to. This is where the conversation begins.
The browser asks that server for the document the user
requested and also supplies some additional attributes about
the request. This is the request. The most important part of
the request is the document that is being requested. This
takes the form of a URL-path (URL-path on page 54).
The Web server accepts the conversation from the browser.
Part of this, is receiving the URL-path. The server then
decides what is being requested and how to handle the
request. If everything is okay, the server sends back to the
browser some attributes about what is being served, and then
the server sends back the content of the document. Both
sides then end the conversation.
It is important to note that there is no login process with
HTTP nor is there an on-going conversation between browser
and server. Unlike other Internet protocols such as FTP and
Telnet, a user does not, in normal operation, provide a
userid and password, or start a user-specific job on the
server machine. Also, each browser request is treated as a
single entity. So, if a browser needed to get several
documents from the same server, the browser would initiate a
separate request for each document.
Page 46
Commerce Server/400 2.0 Using Commerce Server/400
2.2 What is a Commerce Server?
NOTE:
The discussion contained here is only applicable to
owners of Commerce Server/400. Web Server/400 owners
cannot perform secured transactions.
2.2.1 Overview
What does Commerce Server/400 provide you that Web
Server/400 doesn't?
2.2.1.1 Encryption
This allows private conversations over the public Internet.
Using Commerce Server/400, you are able to have a browser
obtain information off of your Web site in the same way that
browsers access your Web Server/400 Web site today. But,
when that data is transferred between machines, it is
completely encrypted. Even someone that can tap the wire
between the machines cannot understand the communications.
The same is true for data typed into an HTML form such as
credit card numbers, secret codes, personal information, or
sensitive corporate information. This data is protected
using strong encryption technologies.
If you are using Webulator/400 today, you can install and
configure Commerce Server/400 on your AS/400 and instantly
have one of the most secure ways of accessing your AS/400
applications. Worried about signing on to your AS/400 over
the Internet from home? With Commerce Server/400 encrypting
your Webulator/400 session, you don't need to worry about
someone grabbing your user ID and password or examining the
screens you view.
2.2.1.2 Integrity
Commerce Server/400 essentially guarantees that the data
sent between the browser and server is unaltered during
transmission. This would detect both transmission errors due
to noisy communication lines and malicious modifications
possibly made by someone in the middle of the server and
browser.
2.2.1.3 Authentication
Commerce Server/400 provides the visitors to your site
confidence that they have reached your site and not someone
else's site trying to impersonate your site. If someone were
to make a purchase from you through your Web site, that
Page 47
Commerce Server/400 2.0 Using Commerce Server/400
person can be confident that they are giving a known company
their credit card number and not an imposter.
2.2.1.4 Nonrepudiation
Commerce Server/400 provides proof that a document that is
served off of your Web site was sent by you to the browser.
For instance, this would allow you to provide a receipt for
an online purchase, including the date of sale, promised
delivery date, and price. The shopper can have confidence in
this receipt because he or she can prove that your Web site
knew of its contents before sending it.
2.2.2 Commerce Serving Basics
In this section, a handful of concepts specific to doing
secured transactions over the World Wide Web are discussed.
These concepts should be clear to anyone administering a
secure Web site. The following section gets into more detail
about how security is implemented. Understanding these
topics is not critical, however the entire picture would be
much more clear if these topics are also mastered.
2.2.2.1 HTTP and SSL
Commerce Server/400 can do everything Web Server/400 can do
plus it can perform secured Web-based transactions. This
means that if you own Commerce Server/400, there is no
reason to also own Web Server/400 for the same machine. In
fact, the two products install into the same location on the
AS/400 so whichever product is installed last will be the
one that is on your AS/400.
Commerce Server/400 and Web Server/400 both serve documents
using the Hypertext Transport Protocol (HTTP). This protocol
does not perform encrypted transactions. The data sent
between the browser and server is sent "in the clear,"
meaning that anyone that can tap into the wire connecting
the two machines can eavesdrop on the conversation.
In addition to HTTP, Commerce Server/400 can also be
configured to encrypt the conversation by interfacing with
the Secure Sockets Layer (SSL) protocol. If both the server
and browser are communicating through SSL, then the HTTP
conversation is done securely. The Secure Sockets Layer
encrypts data as it leaves one machine and decrypts it as it
arrives at the other.
Three ways to set up Commerce Server/400 exist. Commerce
Server/400 can be configured to behave just like Web
Server/400. This means the HTTP communications between the
server and browser would not be encrypted. Commerce
Server/400 can also be configured to only communicate
Page 48
Commerce Server/400 2.0 Using Commerce Server/400
securely with browsers using SSL. And lastly, Commerce
Server/400 can be configured to serve some documents
securely using SSL and some without encryption using only
HTTP. This is done on a per-directory basis using the
Allowed Protocols (section 4.13.1 on page 310) directory
based configuration value.
The first two methods can be combined to form a fourth
option. You can start one instance of Commerce Server/400 to
handle only regular HTTP requests and another to handle only
SSL requests. This can be done by making a separate copies
of the WEBSERV.CFG and ACCESS.CFG configuration files for
the SSL server (e.g., SECURE.CFG and SACCESS.CFG). The HTTP-
only server would set the Protocols configuration value to
HTTP. The SSL-only server would set the Protocols value to
SSL and probably change the Document Root, Include
Libraries, Script Libraries, and possibly other
configuration values. Also, the SSL-only server would need
an Allowed Protocols of SSL in the root directory of the
directory based configuration file (e.g., SACCESS.CFG).
2.2.2.2 Server Certificate
Every server implementing secured transactions requires a
server certificate. This is used to identify the Web site
and to provide browsers with the Web site's Public Key. The
public key is used to provide encryption, integrity,
authentication and nonrepudiation. Server certificates are
obtained from a Certification Authority such as VeriSign,
Inc. A series of commands are provided to assist in the
creation of a server certificate for a Web site.
2.2.2.3 Keylist Database File
A Web site's security information is stored in the keylist
database file. This file is encrypted using a user-supplied
password. The file is reasonably protected by being
encrypted, but it should also be physically guarded as much
as possible.
The server's certificate, public key, and private key are
all stored in this file. The public and private keys are
very large numbers that are used to perform the secure
transactions. Only the private key needs to be closely
guarded. The server's certificate and public key can be
freely distributed.
The server certificate, public key and private key are all
interrelated and must be kept together in the same keylist
database file. If a Web site has more than one certificate,
then multiple keylist database files will be needed. This
might be the case if a Web site is using Multi-home support
to host multiple secure Web sites on the same machine. Each
instance of the server could either share the same keylist
database file (and certificate) or use its own.
Page 49
Commerce Server/400 2.0 Using Commerce Server/400
2.2.3 How Does Commerce Server/400 Do This?
The exact details of how secure electronic communications
are done are not important, but a few of the pieces can be
helpful. The above listed features of a trusted Web site are
accomplished using 1) Server Certificates, 2) Private and
Public Keys, 3) Public Key Cryptography, and 4) Bulk
Encryption Algorithms.
2.2.3.1 Server Certificates
Every Commerce Server/400 server requires a server
certificate. This is used to both prove its identity and to
exchange encrypted information with browsers. The
certificate contains a distinguished name of the server
which is used to uniquely identify the server to visitors,
it contains the server's public key, and it contains a
digital signature of a Certification Authority.
Distinguished Name
This consists of information that uniquely identifies
your Web site. Values such as the Internet host name of
the machine, the company's name, and the State and
country of the company. The Certification Authority will
validate this information before providing a company
their server certificate.
Public Key
The public half of a Web site's encryption key. Visiting
browsers use this value to communicate securely with the
server. This is described more below.
Certification Authority
A Certification Authority (CA) provides server
certificates. Before a company can begin doing secure
transactions, they need to request a server certificate
from a CA. The CA will verify the identity and validity
of the company's request for a server certificate and
then provide a digitally signed server certificate. The
company will then install this certificate into their Web
server software.
Digital Signature
Using sophisticated mathematical algorithms, a digital
signature of a document can be created that proves the
identity of the signer and verifies the contents of the
document. In the case of a server certificate, if the CA
digitally signs the distinguished name and public key
portions of the certificate, then anyone that trusts the
CA can be confident that the certificate has not been
changed.
Page 50
Commerce Server/400 2.0 Using Commerce Server/400
2.2.3.2 Private and Public Keys
Part of the process of generating a server certificate is
generating a pair of large numbers. One of these numbers,
the public key, is shared with everyone who wants to
communicate with the Web site. The other number, the private
key, is only known to the Web site and its administrator(s).
The private key is held in the strictest of confidence.
Commerce Server/400 stores this in its keylist database
file, encrypted using a user-supplied password.
2.2.3.3 Public Key Cryptography
Public Key Cryptography is used to do two things: exchange
bulk encryption keys and verify digital signatures. What is
special about Public Key Cryptography is that anyone who
knows a person's public key can use it to encrypt a message
for that person that no one else can understand. The only
way to decrypt that message is using the private key half of
the public and private key. The opposite is also true:
Something encrypted with a private key can only be decrypted
with the public key. This allows two parties to communicate
without previously exchanging a secret password.
In terms of Web serving, the Web site's public key is
provided to anyone that wants to securely communicate with
that server. This is done by sending the server's
certificate (which contains the public key) to a browser
that wants information from the server. The browser then
uses the server's public key to encrypt a password that will
be used to encrypt the rest of the communication between the
server and browser. Since the server is the only one that
knows its private key that can decrypt something encrypted
with its public key, the server is the only one that can
successfully decrypt the password.
Public Key Cryptography is also used to verify digital
signatures. When a CA digitally signs a certificate, it is
really encrypting a piece of the certificate data using the
CA's private key. When a browser wishes to verify that
signature, it decrypts the signature using the CA's public
key and compares it to the certificate data. If they match
then the digital signature is valid.
2.2.3.4 Bulk Encryption Algorithms
In the discussion on Public Key Cryptography, the browser
encrypted a password that would then be used by both sides
to encrypt the rest of the data. Public Key Cryptography
could be used to do all the encryption between the browser
and server, but it has two disadvantages: This would require
that the browser also has a public and private key so the
server can securely encrypt data sent to the browser. And,
Public Key Cryptography is computationally very expensive.
Page 51
Commerce Server/400 2.0 Using Commerce Server/400
Instead of using Public Key Cryptography for the entire
transaction, only a secret key, or password, is exchanged
using this algorithm. Then this secret key is used by both
sides to perform simpler and faster bulk encryption
algorithms.
Page 52
Commerce Server/400 2.0 Using Commerce Server/400
2.3 URL Locations
2.3.1 OS/400 File Systems
Where Web Server/400 stores Web content differs from most
Unix and PC based Web servers. This is due to the rich
variety of file systems that OS/400 supports. Each file
system is available for different purposes, each having its
own uses and specialties.
QSYS
QSYS is what most people refer to as the file system of
OS/400. It consists of libraries and objects. Some of the
types of objects are database files, programs, and
spooled files.
QDLS
The common names for this are Document Library Services
(DLS) or shared folders. Office Vision/400 uses DLS to
store data generated by Office users. Shared folders is
the file system accessible by PC Support/400 clients.
Root
With the release of V3R1 of OS/400, a new Integrated File
System (IFS) was introduced. IFS is an all-encompassing
file system that includes all of the above file systems
and additional ones. The "Root" file system is part of
IFS and is based on Unix. In these pages, "Root" will
refer to all file systems in IFS except QSYS and QDLS.
IFS can be accessed through a new set of commands and
APIs and also through the new Client Access/400 clients.
In comparison, a Unix product would only access data off of
one file system (one similar to the Root file system). On an
AS/400, supporting only a subset of the above file systems
would be extremely limiting. Each file system has its own
advantages and uses (section 2.3.11 on page 63) making them
all useful for storing data served by a Web server.
2.3.2 Uniform Resource Locator
A Uniform Resource Locator (URL) describes where to find
something of interest stored somewhere on the Internet. A
URL has enough information in it to uniquely describe any
resource on any host anywhere in the world. The basic form
of a World Wide Web URL is:
http://server:port/URL-path?Query String
where,
Page 53
Commerce Server/400 2.0 Using Commerce Server/400
http://
is the protocol being used. Over the Web, the Hypertext
Transfer Protocol (HTTP) is used. This is the language
spoken between servers and browsers.
server
is the fully qualified domain name of the machine that
contains the resource.
port
is the socket port on the host machine that is running
the HTTP server. The :port is optional. If the port is
not included, it defaults to port 80.
URL-path
is the fully qualified, hierarchical path to the
resource. This can be based on the machine's file system
hierarchy or an arbitrary (but unique) naming scheme. An
empty URL-path is valid.
Query String
The Query String begins with the first unescaped question
mark ("?") after the URL-path. This is generally used to
pass parameters into scripts or to modify the default
behavior of serving a Web document.
2.3.2.1 URL Examples
http://www.inetmi.com/samples/document.html
Identifies the file document.html in the samples
directory on the host www.inetmi.com. The request is an
HTTP request that is handled by the Web server running on
port 80 (the default).
http://www.inetmi.com:2064/samples/
Identifies the directory samples on the host
www.inetmi.com. The request is an HTTP request that is
handled by the Web server running on port 2064.
http://your.host.net/company/info/employee/profile/jane_doe.
jpg
Identifies the image jane_doe.jpg in the
/company/info/employee/profile/ subdirectory on the host
your.host.net. The request is an HTTP request that is
handled by the Web server running on port 80 (the
default).
2.3.3 How Web Server/400 Finds a Web Document
Three factors come into play when the server attempts to
locate the resource that is requested by the browser:
Page 54
Commerce Server/400 2.0 Using Commerce Server/400
. the URL-path,
. the source file system, and
. the root of all documents on that file system.
2.3.3.1 URL-Paths
Once a server starts handling a request from a browser, the
URL-path is the most interesting portion of a URL. The other
portions of a URL are responsible for correctly routing the
request to the proper host. The Web server then takes the
URL-path and determines what should be sent back to the
browser.
URL-paths are typically hierarchical with the structure
indicated by names separated by slashes ("/"). This is very
similar to path names on Unix or PC file systems or OS/400's
new IFS. In fact, for the most part Web Server/400 does map
a URL-path's hierarchy directly to IFS's directories and
files. So when a browser requests a URL-path of
/abc/xyz.html, the server looks for a directory called abc
with a file in it called xyz.html.
2.3.3.2 The URL's Source File System
Web Server/400 determines which file system contains the
data needed to serve a request through configuration values,
aliases, and the URL-path. The URL-path is checked to see if
it begins with a configured alias. If it does not, the
Default Source Type (section 4.13.3 on page 311)
configuration value indicates where the URL-path points to.
If the URL-path does begin with an alias, the alias (section
4.3.1 on page 261) can indicate a file system to use other
than the default.
2.3.3.3 The Source File System's Document Root
All three file systems, QSYS, QDLS, and Root, have a
different location to begin looking for files in that file
system. This location is referred to as the Document Root.
All URL-paths are relative to the appropriate Document Root.
The Root and QDLS file systems each have configurable
document roots that are quite similar: Document Root
(section 4.6.2 on page 271) and Document Root QDLS (section
4.6.3 on page 272), respectively.
The QSYS file system really has two document roots.
1.The Document Root QSYS (section 4.6.4 on page 273) is
similar to the Root and QDLS document roots. QSYS's
document root is configurable and URL-paths are
searched for in this library. However, not all URL-
paths are considered relative to the Document Root
QSYS. Only URL-paths that do not include an explicit
library are relative to the Document Root QSYS library.
Page 55
Commerce Server/400 2.0 Using Commerce Server/400
So, a URL-path that contains only a file and member
would be considered relative to this special library.
This is especially useful when the Default Source Type
(section 4.13.3 on page 311) is set to QSYS. Then the
Index Name (section 4.13.7 on page 315) Web document is
pulled from the Document Root QSYS library if it
doesn't have a path on the beginning of it. Note: Be
sure to add the library specified by Document Root QSYS
to the Include Libraries configuration value.
2.The other QSYS document root is QSYS itself. All
references to URL-paths that have a library in them are
relative to QSYS. This is because all libraries are in
QSYS and QSYS is the only library that can contain
libraries. This limited hierarchy forces URL-paths with
library names to be relative to QSYS.
2.3.3.4 An Example
An example is in order. Assume that the Default Source Type
is the Root file system and that an alias exists that maps
all /library/ references to /qsys.lib/ and that the Document
Root for the Root file system is set to /webpages/. If a
user requests a URL-path of /info/page.html, then the server
would look in the Root file system for the file to serve
since info is not aliased and the Default Source Type is the
Root file system. The server would then make the URL-path
relative to the Document Root. This would cause it to look
for the file /webpages/info/page.html.
If the user requests a URL-path of
/library/ProdData.lib/Prices.file, the server would look in
the QSYS file system for the file since the alias maps all
references beginning with /library/ to files in QSYS. It
would then look for the file PRICES in the library PRODDATA.
2.3.4 Special URL-paths
Although a URL-path is generally directly mapped to a file
system's directory structure, this doesn't have to be the
case. In several cases, Web Server/400 defines a logical
URL-path to a physically different file system path. The
usual reason for this mapping is to fit a feature of OS/400
into something consistent with typical URL-paths. This makes
for a more seamless integration of OS/400 concepts with the
WWW.
The details of URL-paths are separated out by file system
and type of resource being referred to:
. Root URL-Paths (section 2.3.5 on page 57)
. QDLS URL-Paths (section 2.3.6 on page 57)
. QSYS URL-Paths (section 2.3.7 on page 58)
Page 56
Commerce Server/400 2.0 Using Commerce Server/400
. USF URL-Paths (section 2.3.8 on page 60)
. Dynamic Indexing (section 2.3.10 on page 61)
2.3.5 Root URL-Paths
2.3.5.1 Root URL-Path Format
A URL-path is considered a Root URL-path if Root is the
Default Source Type or if the URL-path begins with an alias
that has a Source Type of Root. The only real difference
between how Web Server/400 treats Root URL-paths and how IFS
treats paths in the Root file system is that the URL-paths
are always relative to the directory stored in the Document
Root configuration value.
2.3.5.2 Symbolic Links in URL-paths
URL-paths themselves cannot containing symbolic links, but
the files they represent in IFS can be symbolic links
(section 2.3.12 on page 64). The Root file system is
currently the only file system that supports the creation of
symbolic links. Symbolic links can, however, point to files
that reside in any file system.
2.3.5.3 Root URL-Path Examples
For these examples, assume that /Samples/ is a valid
directory off of Document Root, Document Root (section 4.6.2
on page 271) is set to /WWWServ/WebDocs/, and that Root is
the Default Source Type. With this setup, each of the
following requests would be handled as described.
A URL-path of /Samples/Environmental/Pinetrees.html
The Web server would return the file
/WWWServ/WebDocs/Samples/Environmental/Pinetrees.html to
the browser.
A URL-path of /Samples/SymLink/ProdDB
Assuming that /WWWServ/WebDocs/Samples/SymLink is a
symbolic link to /qsys.lib/company.lib, the Web server
would return the formatted fields of the first member of
the database file /qsys.lib/company.lib/ProdDB.file to
the browser.
2.3.6 QDLS URL-Paths
2.3.6.1 QDLS URL-Path Format
A URL-path is considered a QDLS URL-path if QDLS is the
Default Source Type or if the URL-path begins with an alias
that has a Source Type of QDLS. URL-paths in QDLS are
treated by Web Server/400 in nearly the same way as IFS
treats them. There are two main differences:
Page 57
Commerce Server/400 2.0 Using Commerce Server/400
. The Document Root QDLS is added to the beginning of the
URL-path.
. File names that do not fit the 8.3 format are converted
to 8.3.
2.3.6.2 Document Root QDLS
All QDLS URL-paths are relative to the directory specified
by the Document Root QDLS configuration value.
2.3.6.3 Conversion to 8.3 Format
The QDLS file system supports files with one to eight
characters in the main portion of the name, optionally
followed by a period and up to three additional characters.
Many of the content types that are common for Web documents
have names that are longer than three characters, and it is
common to have names that are longer than eight characters.
Web Server/400 will convert a filename that is in QDLS to
fit the 8.3 naming convention by truncating each portion to
its maximum length. This conversion is not performed on the
subdirectory names leading up to the file name.
2.3.6.4 QDLS URL-Path Examples
For these examples, assume that /SharedFolders/ is aliased
to / in QDLS and Document Root QDLS is set to
/qdls/WebDocs/. With this setup, each of the following
requests would be handled as described.
A URL-path of /SharedFolders/products/inventory.html
The Web server would return the file
/qdls/WebDocs/products/inventor.htm to the browser.
Notice that the y in inventory and the l in html were
dropped to convert the name to 8.3 format.
A URL-path of /SharedFolders/Incorporated/news.txt
This URL-path would not be found since the subdirectory
Incorporated is too long for a QDLS directory name and
Web Server/400 does not do conversions on directory
names.
2.3.7 QSYS URL-Paths
2.3.7.1 QSYS URL-Path Format
Web Server/400 represents URL-paths pointing into QSYS in a
way very similar to how the new IFS represents them. The
following rules summarize how IFS represents objects in
QSYS:
. Host objects are represented by the object name
followed by an extension that indicates the object's
type.
Page 58
Commerce Server/400 2.0 Using Commerce Server/400
. All paths to QSYS objects begin with /qsys.lib.
. The QSYS library is the only library that can contain
other libraries.
. The only two object types that can contain other
objects are libraries and files. A library can contain
any object type except members and other libraries
(excluding QSYS). The only object type that files can
contain are members.
For instance, the file PRICES stored in library CORPDATA
could be represented as /QSYS.LIB/CORPDATA.LIB/PRICES.FILE.
If the PRICES file had a member called WIDGET, then that
member could be represented as
/QSYS.LIB/CORPDATA.LIB/PRICES.FILE/WIDGET.MBR.
2.3.7.2 Web Server/400 and IFS Differences
Listed here are the major differences between the way IFS
handles files in QSYS and the way Web Server/400 handles
them:
Object type extensions are not always necessary
With Web Server/400 the object type extensions are
optional. If the object name is enough to make the object
unique, the extension is not needed. If more than one
object in a library or file has the same name, the object
type extension is required. Note: When determining if an
object's name is unique, only object types of .LIB,
.FILE, .MBR, and .PGM are considered.
Content Type extensions can be included
A URL-path can optionally include a Content Type (section
5.2.3 on page 340) extension on files and members. The
Content Type extension is not part of the actual object
name and must come after the object type extension if one
is present.
A file's member is defaulted if not specified
If a file is specified with no member, this is the same
as specifying the file with its first member.
A file with a trailing slash returns a dynamic index
A URL-path that includes a trailing slash after an object
that has type .FILE is considered a request for a dynamic
index.
Symbolic links to objects in QSYS
Some restrictions exist (Symbolic links to files in QSYS
on page 64) for having symbolic links in IFS to objects
in QSYS.
Page 59
Commerce Server/400 2.0 Using Commerce Server/400
2.3.7.3 QSYS URL-path Examples
For these examples, assume that /NATIVE/ is aliased to
/QSYS.LIB/ in QSYS and that CORPDATA is in the Include
Libraries (section 4.9.1 on page 292) configuration value
but not in the Script Libraries configuration value. With
this setup, each of the following requests would be handled
as described.
A URL-path of /NATIVE/CORPDATA/PRICES/WIDGET
The member /QSYS.LIB/CORPDATA.LIB/PRICES.FILE/WIDGET.MBR
would be sent assuming that QSYS.LIB does not contain a
file named CORPDATA.FILE. If this file did exist, this
URL-path would be rejected as not found since the
CORPDATA name wouldn't be unique in its library.
A URL-path of /NATIVE/CORPDATA.LIB/PRICES/WIDGET.MBR.HTML
The member /QSYS.LIB/CORPDATA.LIB/PRICES.FILE/WIDGET.MBR
would be sent as HTML.
A URL-path of /NATIVE/CORPDATA.LIB/PRICES.TXT
In this case, the first member of the file
/QSYS.LIB/CORPDATA.LIB/PRICES.FILE would be sent as
plain/text.
A URL-path of /NATIVE/CORPDATA/PRICES/
Because of the trailing, slash a dynamic index of
/QSYS.LIB/CORPDATA.LIB/PRICES.FILE/ would be returned.
2.3.7.4 Providing Access to QSYS Libraries
Because of the limited hierarchy depth found in the QSYS
file system, a different mechanism is used to protect non-
Web content data from being served by Web Server/400. The
other file systems have a Document Root configuration value
that limits access to Web documents to a subdirectory of the
Document Root. The QSYS file system has, instead, a
configuration value that lists all libraries that Web
Server/400 can serve documents out of. If the library
specified by a URL-path is not included in the Include
Libraries configuration value, the request is rejected.
A wildcard of an asterisk can be used to indicate that any
library that has the same beginning as the library in the
Include Libraries directive, up to the asterisk, is
accessible.
2.3.8 USF URL-Paths
2.3.8.1 USF URL-Path Format
A URL-path is considered to be a USF URL-path if it begins
with an alias that indicates it is a USF Object. USF URL-
paths are always followed by the Object ID of an object in
USF's multimedia repository.
Page 60
Commerce Server/400 2.0 Using Commerce Server/400
If the object referred to is not a multimedia object (e.g.,
the object is a container or a device), then an error is
returned to the browser. Also, if USF isn't installed on the
AS/400 running Web Server/400, an error is returned to the
browser.
2.3.8.2 USF URL-Path Examples
For this example, assume that /Multimedia/ is an alias that
has a Source Type (section 4.3.1 on page 261) of *USFOBJ. If
a URL-path of /Multimedia/HGSJ748362HGZK485763 is requested,
the USF object with the Object ID HGSJ748362HGZK485763 would
be found in the repository and the multimedia data
associated with it would be returned to the browser. This
might be an image, an audio, or an HTML file. Its content
type is determined by the extension of the file in the
multimedia repository.
2.3.9 Spooled File URL-Paths
2.3.9.1 Spooled File URL-Path Format
A URL-path is considered to be a Spooled File URL-path if it
begins with an alias (section 2.4 on page 65) that has a
Source Type of *SPLF. Spooled File URL-paths are followed by
information that uniquely identifies the spooled file
(section 2.10 on page 134) that is requested. This includes
all or some of the following: Job Name, User Profile, Job
Number, and Spooled File Name.
In addition, the Spooled File Name can have a valid content
type as an extension. If it does, the content type extension
is not considered part of the Spooled File Name. A valid
content type will be used to set the content type of the
result of the request.
Spooled Files can contain HTML markup. If these files have
hyperlinks to other documents, the references can still be
relative to the current URL. For example, assume that /SPLF/
is setup as a spooled file alias and the URL-path
/splf/job/george/123456/report has a hyperlink of
../654321/report2. If the first URL-path is requested and
the user selects the hyperlink that it contains, the browser
will request /splf/job/george/654321/report2.
2.3.10 Dynamic Indexing URL-Paths
2.3.10.1 Dynamic Indexing URL-Path Format
A URL-path that ends with a slash ("/") will either generate
a dynamic index (section 2.14 on page 144) or will use an
already created index file. Whenever a URL-path that ends in
Page 61
Commerce Server/400 2.0 Using Commerce Server/400
a slash is received, Web Server/400 checks to see if a Web
document with the name defined in Index Name exists in the
directory pointed to by the URL-path. If one does, that Web
document is sent. If not, and the server is configured to do
so (section 4.7.2 on page 278), an index of the contents of
the URL-path is dynamically created and sent back to the
browser.
NOTE: When referencing Web documents found in the QSYS file
system, both libraries and files are considered directories.
That is, putting a slash on the end of a physical file name
will bring up either the member named with the Index Name or
a dynamic index of the members in the file. A library with a
trailing slash will either send a file named with the Index
Name or a dynamic index of all the objects in the library.
2.3.10.2 Dynamic Indexing URL-Path Examples
A URL-path of /index/
The index name is an alias which maps to the
/samples/index/ directory in the IFS root file system.
The dynamic index view of the index directory would be
shown assuming that a file with the Index Name does not
exist within the directory.
A URL-path of /Samples/index/
The dynamic index view of the index directory would be
shown assuming that an index file did not exist within
the directory. This is the same view as the previous
example except that an alias was not used in this
example.
A URL-path of /QSYS/WWWSAMPLES.LIB/
The QSYS name is an alias which maps to the QSYS library
within the QSYS file system. The dynamic index view of
all the files within the WWWSAMPLES library would be
shown assuming that a file named the same as the Index
Name did not exist within the library.
A URL-path of /QSYS/WWWSAMPLES.LIB/SAMPLE.FILE/
The QSYS name is an alias which maps to the QSYS library
within the QSYS file system. The dynamic index view of
all the members within the SAMPLE physical file residing
in the WWWSAMPLES library would be shown assuming that an
index member did not exist within the file.
A URL-path of /QDLS/Samples/
The QDLS name is an alias which maps to the Document Root
QDLS within the QDLS file system. The dynamic index view
of all the files within the Samples directory assuming
that an index file does not exist within the directory.
Page 62
Commerce Server/400 2.0 Using Commerce Server/400
2.3.11 OS/400 File Systems
What file systems does Web Server/400 support? Below is a
list of the supported file systems and a short description
of the strengths of each.
QSYS
Most of the existing AS/400 applications deal with data
stored in QSYS. All DB2/400 databases and OS/400 programs
exist here.
QDLS
Many installations are currently setup to have PCs attach
to their AS/400 through the DOS Extended and OS/2 1.x
versions of Client Access/400. These clients are usually
setup to access shared folders. This allows for easy
access to stream files on the host that can be served by
Web Server/400. It is also much easier to store typical
Web multimedia content in QDLS than in QSYS.
Root
Being the newest file system, this is the most efficient
and flexible file system for accessing stream files. New
products, such as the new WIN16 and OS/2 Optimized
clients of Client Access/400, are supporting the Root
file system. The names of files and depth of directories
have no practical limit. The speed of this file system
makes it ideal for serving and creating large Web
documents.
IFS currently has two specialized file systems under it
called QOpenSys and QLANSrv. QOpenSys only has one
distinction between it and the rest of the root file
system: files and directories are case sensitive. A file
named HEADER.HTML is different from a file named
header.html. This is the way a standard Unix file system
works. If you are transferring a Web site from a Unix
machine to Web Server/400 and the Unix Web site depended
on the case of file names and directories, moving the
files into QOpenSys and setting up your Document Root to
point to a directory under the QOpenSys file system would
support this seamlessly.
The QLANSrv file system has some advantages and
disadvantages for being used with Web Server/400. One
advantage is the workstations attached to the AS/400 with
an FSIOP and the LAN Server/400 product can easily and
quickly access the content on the Web site. However,
there are two disadvantages as well.
1. Accessing files in QLANSrv from the AS/400 is
actually relatively slow. This file system's speed
advantages are only obtainable from workstations.
Page 63
Commerce Server/400 2.0 Using Commerce Server/400
2. Normal AS/400 security is not implemented in the
QLANSrv file system. LAN Server/400 is responsible
for the security and it implements a different
security model than that of the AS/400.
It should also be noted that QLANSrv is not accessible
unless you have the LAN Server/400 product installed.
2.3.12 Symbolic Links
A symbolic link is a special file in the root of IFS that
has no size or content. A symbolic link points to another
file or directory in IFS. All accesses to a symbolic link
actually access what the link points to.
Web Server/400 allows symbolic links inside the document
hierarchy. Symbolic links to files outside the hierarchy are
allowable as long as the Server User Profile (section
4.13.17 on page 324) has *RX permission to the file and *X
permission to all directories in the file's real path. For
files in the QDLS file system, the Server User Profile
(section 4.13.17 on page 324) must have *USE permission to
all the directories in the file's real path and to the file
itself.
Symbolic links to files in QSYS are allowed for source
physical files and program-described physical files
containing a single field. However, in order for a symbolic
link to successfully follow a link to a QSYS object, the
link can only be the last element in the URL. For example,
if the path /link/ is a symbolic link to
/qsys.lib/wwwsamples.lib/, then a request for the Web
document /link/ would return a dynamic index of
/qsys.lib/wwwsamples.lib/. But, a request for the Web
document /link/SampleDoc.file would not work because the
symbolic link in this path is not the last element of the
URL (/SampleDoc.file).
Very long paths in the Root file system can be supported by
using shorter symbolic links that point to deeper paths.
Page 64
Commerce Server/400 2.0 Using Commerce Server/400
2.4 Aliases
2.4.1 Mapping a URL-Path to a Different Location
The main purpose of an alias is to re-route a browser's
request from one location to another. The new location can
be just a different directory on the current server or it
could be a complete URL to a different server.
Using the command WRKWWWALS (section 3.3.16 on page 217), a
list of aliases and the values that they should be mapped to
are configured. The server checks every URL-path to see if
an alias substitution should occur. If the URL-path begins
with an alias, the value the alias is mapped to replaces the
aliased portion of the URL-path and appends the end portion
of the URL-path to the new URL-path. The replaced portion
can be the first directory, the first several directories,
the whole URL-path, or any beginning portion of a URL-path.
Note that Web Server/400 supports begins with (Begins-with
match on page 69) alias matching. This means that the only
time an alias substitution occurs is when the beginning of a
URL-path matches a configured alias. This comparison is
case-insensitive.
2.4.1.1 Alias Examples
In this example, assume the following aliases have been
configured, the Default Source Type is Root, and the Index
Name (section 4.13.7 on page 315) is index.html.
/abcdef/
maps to /xyz/
/one/two/three/
maps to /four/five/
/pop
maps to /soda
/popcorn
maps to /corn
With this setup, each of the following requests would be
handled as described.
A URL-path of /AbCdEf/webpage.html
The server would accept this request and return the file
/xyz/webpage.html.
Page 65
Commerce Server/400 2.0 Using Commerce Server/400
A URL-path of /one/two/three/
The server would accept this request and return the file
/four/five/index.html. The index.html is placed at the
end since this is the default Web document for all
directories. This would only be returned if it existed in
/four/five/. Otherwise, a dynamic index of /four/five/
would be returned.
A URL-path of /popcornball/promo.gif
Since the server does a maximal match (Maximal matching
on page 69) on alias names, the server would return
/cornball/promo.html. The /popcorn portion was mapped to
/corn and the remaining portion of the URL-path,
ball/promo.gif was appended to that.
2.4.2 Using Aliases to Access Other File Systems
Aliases are also used to indicate which file system (How Web
Server/400 Finds a Web Document on page 54) a URL-path
resides on. Each alias can have an associated type with it,
the Alias Source Type (section 4.3.1 on page 261). Using
this, any requested URL-path can be mapped to a directory in
any file system.
2.4.2.1 Examples of Aliases and Other File Systems
In this example, assume the following aliases have been
configured, the Default Source Type (Default Source Type on
page 55) is QDLS, Document Root (The Source File System's
Document Root on page 55) is set to /webpages, and Document
Root QDLS (The Source File System's Document Root on page
55) is set to /qdls/webpages.
/native/
maps to /library1/ in QSYS.
/images/
maps to /images/ in Root.
/info
maps to /data with no specified file system.
With this setup, each of the following requests would be
handled as described.
A URL-path of /native/webpage.html
The file webpage in library library1 would be served out
of QSYS as an HTML file.
A URL-path of /images/dog.jpg
The file /webpages/images/dog.jpg would be returned.
Page 66
Commerce Server/400 2.0 Using Commerce Server/400
A URL-path of /info/cat.html
The file /qdls/webpages/data/cat.htm would be returned.
Notice that the filename was converted to an 8.3 format
since this request was served from QDLS.
2.4.3 Using Aliases to Access Special Web Documents
In addition to mapping URL-paths from one location to
another, aliases are used to indicate that a URL-path should
reference a special Web document type. Three special types
are supported: Webulator/400 Applications, USF Objects, and
Spooled Files.
Webulator/400 Applications
Webulator/400 applications are accessed by creating an
alias with a Source Type of *WEBULATOR. Then, any URLs
that begin with this alias are handled by the
Webulator/400 feature of Web Server/400. Everything that
occurs after the alias defines the application
configuration to run.
For example, if /WEBULATOR maps to /WIDGET with a source
type of *WEBULATOR then asking for the URL
/WEBULATOR/ORDER would cause Webulator/400 to use the
configuration values setup for the directory (section
4.2.12 on page 254) /*META/WEBULATOR/WIDGET/ORDER.
USF Objects
USF Objects can be accessed (section 2.11 on page 140)
through Web Server/400. This access is opened up by
specifying an alias that is has a Source Type of *USFOBJ.
Then, any URL-path that begins with this alias will be
treated as a URL that references a USF Object (section
2.3.8 on page 60). When configuring USF Object aliases,
the value that the alias maps to should not be specified.
Spooled Files
An alias is used to indicate a URL-path references a
Spooled File. A URL-path that begins with an alias that
has a Source Type of *SPLF indicates that the URL-path
references an AS/400 spooled file. When configuring
Spooled File aliases, the value that the alias maps to
should not be specified.
2.4.4 Using Aliases to Redirect URLs to Different Servers
A Web server has the ability to tell a Web browser to look
for a URL at a certain location on an entirely different Web
server. This is referred to as Redirection. This might be
useful if a Web document or a set of Web documents are
removed from one server, and relocated to another. Existing
HTML documents with links to the old documents will still
Page 67
Commerce Server/400 2.0 Using Commerce Server/400
work since the server will redirect them automatically to
the new location. Also, people that have a URL in their
quicklist will still be able to find Web documents that have
moved.
URL redirections can be permanent or temporary:
Permanent
The new URL will be in effect indefinitely and it is not
planned to have the old URL be valid anymore.
Temporary
The redirection is only temporary. The old URL will be
effective again or the redirection could change to
something else at any time.
When redirecting a URL-path the entire new URL must be
specified. This includes the protocol, server, port, and
URL-path.
2.4.4.1 Examples of Alias Redirection
In this example, assume the following aliases have been
configured, the Default Source Type (Default Source Type on
page 55) is QDLS, Document Root (The Source File System's
Document Root on page 55) is set to /webpages, and Document
Root QDLS (Document Root QDLS on page 58) is set to
/qdls/webpages.
/xyz/
maps to http://new.server.com:5000/xyz/ (permanently).
/abc/
maps to http://new.server.com/ (temporarily).
With this setup, each of the following requests would be
handled as described.
A URL-path of /xyz/webpage.html
The server would send back a response to the browser
indicating that this URL has moved permanently to
http://new.server.com:5000/xyz/webpage.html.
A URL-path of /abc/webpage.html
The server would send back a response to the browser
indicating that this URL has moved temporarily to
http://new.server.com/webpage.html.
2.4.5 Alias Matching
These are some important points regarding aliases that you
should know prior to setting up aliases.
Page 68
Commerce Server/400 2.0 Using Commerce Server/400
Begins-with match
A check is only made to see if a URL-path matches an
alias from the very beginning of the URL-path. An alias
that appears in the middle or at the end of a URL-path is
ignored.
Leading slash
All aliases should begin with a slash since all URL-paths
begin with a slash. If the alias did not have a leading
slash, it would never be found in a URL-path because only
begins-with matching is done with aliases.
Maximal matching
If two aliases that begin the same are defined, the
server has to decide which alias substitution to use on a
URL-path that begins the same as both aliases. The server
always uses the longest alias that still matches. For
example, if an alias /abc maps to /uvw and alias /abcdef
maps to /xyz and the URL-path /abcdef/web.html is
requested, the server has to decide if this should be
converted to /uvwdef/web.html or /xyz/web.html. Web
Server/400 does a maximal match which means that the
longest matching alias will always be picked. In this
example, /xyz/web.html would be used since it comes from
the longest matching alias (/abcdef).
Trailing slashes
You should avoid having an alias without a trailing slash
point to a directory with a trailing slash. If an alias
is setup like this, any references within the resulting
page will not work since the browser will not know that
the resulting page is a directory. For example, if you
have an alias /xyz mapped to /abc/, and a browser
requests /xyz, a dynamic index of /abc/ will be shown. If
the user then selects a file from within the dynamic
index, the browsers will make that selection relative to
/ rather than /xyz/ since to the browser, the original
request was for a file not a directory.
Aliasing one HTML document to another
Having an alias that maps one HTML file to an HTML file
in a different directory will work but all embedded links
within the resulting HTML document will be relative to
the directory of the original URL rather than to the
directory where the HTML file was actually found. For
example, assume the alias /company/homepage.html maps to
/branch/index.html and that /branch/index.html contains
the embedded image logo.gif which resides in the /branch
subdirectory. If a browser requests
/company/homepage.html, the server will return
/branch/index.html as expected, but the embedded image
will not be found since the browser will try to load it
from the server with the URL /company/logo.gif rather
than the desired URL /branch/logo.gif. To get around
Page 69
Commerce Server/400 2.0 Using Commerce Server/400
this, create an alias that maps /company/ to /branch/.
The server then maps all requests to the new directory.
Page 70
Commerce Server/400 2.0 Using Commerce Server/400
2.5 NLS Architecture
Web Server/400 implements National Language Support (NLS)
with the services provided by OS/400, the AS/400 operating
system. This means that Web Server/400 has some of the same
NLS strengths and weaknesses as OS/400.
This section is especially useful for non-U.S.
installations. The World Wide Web and the Internet are
becoming more internationally-aware, but some inconveniences
still exist for non-U.S. Web sites. This section provides
assistance in configuring a successful Web site for all
national languages.
2.5.1 NLS Definitions
The following terms which are used to discuss National
Language Support (NLS) may be unfamiliar to you:
CCSID
A number which identifies an encoding scheme (see ESID),
and one or more code pages. This is all that is needed to
correctly interpret text data.
Character set
A defined set of characters. No mapping between
characters and values is assumed.
Code page
Specifies a mapping between values and characters for one
or more character sets.
Double-byte code page
A code page in which each character is represented by two
bytes.
ESID
Encoding scheme identifier. An encoding scheme specifies
the way that text data is interpreted. It includes
information such as whether the text is ASCII or EBCDIC.
ISO character set
The ISO mechanism for cataloging ways of interpreting
text data. This has a correspondence to CCSID.
Single-byte code page
A code page in which each character is represented by one
byte.
Page 71
Commerce Server/400 2.0 Using Commerce Server/400
2.5.2 Serving Content
When reading a content file, the server has to know in what
CCSID it is stored. It uses the File CCSID (section 4.13.6
on page 314) configuration value to do this. In addition to
any valid CCSID, the File CCSID may be set to zero or to
NoConvert. Zero tells Web Server/400 to use the file's
associated codepage as a CCSID. NoConvert tells Web
Server/400 to serve the file in binary mode; no conversion
is performed.
Web Server/400 converts content files as it reads them.
Depending on the type of content file, it may first convert
it to the server job CCSID, then to the content CCSID, or it
may convert the file directly to the content CCSID. NLS flow
(section 2.5.9 on page 74) has more information.
2.5.3 Serving Webulator Screens
To serve double-byte screens, change the Terminal Size
parameter to DBCS. No changes are needed for non-double-byte
screens.
2.5.4 Reading Configuration Files
When reading a configuration file, Web Server/400 needs to
know what CCSID the file is in so that it can be converted
correctly. In most cases, the file's associated codepage is
used. Additionally, the CCSID for the Directory based
configuration file (section 4.2.13 on page 255) can be
explicitly entered. This is supported to make it easier to
enter mixed byte data in the directory based configuration
file. The root file system does not allow the specification
of mixed byte CCSIDs unless they are in QSYS.
2.5.5 Conversion Methods
OS/400 conversion routines are used to convert data. When
converting data, Web Server/400 will keep trying different
methods until one succeeds or all have been exhausted. Web
Server/400 tries the following methods (in order): best fit,
enforced subset, round-trip. The three methods differ in
what their purpose is and how they handle mismatched
characters (characters that do not convert correctly).
Best fit conversion will attempt to find a close alternative
for a mismatched character. For example, if converting the
letter o with an umlaut above it (o) to a CCSID that does
not contain this character, it might be converted to a o
without an umlaut above it.
Enforced subset conversion deals with mismatched characters
by replacing them with a single substitution character. The
Page 72
Commerce Server/400 2.0 Using Commerce Server/400
substitution character depends on the encoding scheme of the
destination CCSID.
Round trip conversion is meant to allow conversion from one
CCSID to a second, and then back to the first CCSID without
a loss of information. This is the least useful for Web
Server/400, because all conversions are one-way, and so is a
last resort.
If a conversion from a single-byte CCSID to a mixed byte
CCSID fails, Web Server/400 will also attempt a conversion
from the single-byte CCSID to the single-byte codepage of
the mixed-byte CCSID.
2.5.6 CCSIDs and ISO character sets
While OS/400 uses CCSIDs to identify the way text data is
encoded, the World Wide Web uses ISO character sets to
identify the way text data is encoded. Following is a table
showing some of the useful ISO character sets and associated
CCSIDs:
ASCII
ISO character set CCSID
----------------- -----
US-ASCII 367
ISO-8859-1 819
ISO-8859-2 912
ISO-8859-5 915
ISO-8859-7 813
ISO-8859-8 916
ISO-8859-9 920
ISO-2022-JP 5052
Note that ISO-8859-1 (CCSID 819) is the default character
set for HTTP and is the default value for the Content CCSID
(section 4.13.2 on page 311).
2.5.7 Limitations
URLs
URLs (section 2.3 on page 53) must be single-byte except
for the query string, which can be mixed-byte. This is a
limitation of the HTTP specification.
CCSIDs
CCSIDs with an encoding scheme (ESID) of 4403 and 5404
are not currently supported.
File names
All file names must be single byte. This includes
configuration file names and content file names.
Page 73
Commerce Server/400 2.0 Using Commerce Server/400
2.5.8 Related Documentation
The following IBM manuals contain information that may be
useful to you:
Character Data Representation Architecture Level 1
SC09-1390-00
Character Data Representation Architecture Level 2
SC09-1390-01
AS/400 International Application Development
SC41-3603-00
AS/400 National Langauge Support Planning Guide Version 2
GC41-9877-02
2.5.9 Flow of Text Conversion
The figure below shows the kinds of text that Web Server/400
can convert, the transformations that can cause conversions
and configuration values that can affect conversions. This
figure is a useful reference when setting up configuration
values as well as deciding what CCSID to assign to different
user profiles.
. Jobs and Files
Normal Content Files
All files with a content-type of text (e.g. text/plain
and text/html) except those interpreted by the server
and those served from QSYS.
Browsers
The WWW client application (e.g. Netscape Navigator).
The Content CCSID (section 4.13.2 on page 311)
configuration value specifies what CCSID the browser is
assumed to use.
Interpreted/Database Content Files
All files with are interpreted by the server or are
read from QSYS. Files that are interpreted by Web
Server/400 include: Server-side includes (section 2.17
on page 179), files that are dynamically indexed
(section 2.14 on page 144) with titles, dynamic index
headers and footers, and Webulator/400 headers and
footers.
Server Jobs
The CCSID associated with these can be changed by
setting the CCSID for the server user profile (section
4.13.17 on page 324).
Configuration Files (section 5.1 on page 333)
Web Server/400 stores configuration information in IFS
files. These files can have a code page associated with
them. In addition, the directory based configuration
Page 74
Commerce Server/400 2.0 Using Commerce Server/400
file (section 5.4.1 on page 343) can have a CCSID
associated with it via the Directory Based
Configuration File Path (section 4.2.13 on page 255)
configuration value.
Configuration Job
The job that is executing configuration commands
(Configuration Commands on page 194). Someone must be
responsible for setting up Web Server/400 and
maintaining the configuration. This person is also
called the Web Master. This may be the same person who
starts the server (see below) or it may be different.
Server Starter Job
The job that starts the server and causes
reconfigurations (STRWWW (section 3.2.1 on page 197)
and SETWWWCFG (section 3.3.2 on page 209)).
. Conversions
Note that while there are six conversions shown, three
of them are associated solely with starting or
reconfiguring the server. When serving content, at most
two conversions are made. The normal case is one or no
conversions.
Conversion 1
Conversion from the code page associated with content
files to the Content CCSID (section 4.13.2 on page
311). Note that the File CCSID (section 4.13.6 on page
314) configuration value can alter or disable this
conversion.
Conversion 2
Conversion from the code page associated with content
files to the CCSID associated with the server jobs.
Conversion 3
Conversion between the CCSID of the server jobs and the
browser.
Conversion 4
Conversion between the configuration file code page and
the CCSID associated with the job of the user
configuring the server.
Conversion 5
Conversion from all configuration file code pages to
the job of the user starting or reconfiguring the
server.
Page 75
Commerce Server/400 2.0 Using Commerce Server/400
Conversion 6
Conversion from the CCSID of the job of the user
starting Web Server/400 to the CCSID associated with
the server jobs.
Page 76
Commerce Server/400 2.0 Using Commerce Server/400
2.6 Creating Content
How do I get the content to the AS/400 so that the web
server can access and serve the documents? There are a
number of ways to get the content from your PC to the AS/400
(assuming that you are creating your content on a PC and not
directly on the AS/400). If you are creating your content
directly on your AS/400 in a source physical file or
physical file then this discussion is not necessary. We have
found that most customers work on a client
PC/MAC/Workstation to create the content and move the
documents to the AS/400 when they are ready to be served.
The client work environment you are using you will have
different options available to you. This section is not
intended to be a comprehensive list of options available to
you as a user. It is intended to help assist in finding a
method and describe some of the steps and configuration
necessary to transfer the data. FTP and Client Access are
described in detail because they are likely to be available
to most customers. If you have Client Access available, you
should find it the easiest option.
2.6.1 Location for files on your AS/400
The AS/400 has several file systems (section 2.3 on page 53)
available. Ideally, you should put your content into the IFS
root file system. This is faster than other file systems and
supports long file names. This may be difficult depending on
the method you are using to get the content to the AS/400.
2.6.2 Using FTP to Move Your Content
The first option that is available to most all client
environments is to FTP the content from your client to the
AS/400. The difficulty in transferring the content using FTP
V3R1 and V3R6 versions of OS/400 is that you do not have the
ability to transfer files directly into the IFS root file
system. The only file systems supported are the QSYS and
QDLS file systems. The FTP server available with V3R2
version of OS/400 supports the ability to access all IFS
file systems.
The first thing that you need in order to use FTP is client
FTP software. Secondly, your AS/400's FTP server software
must be installed, configured and started. The FTP server is
available as a free option of the operating system (TCP/IP
Connectivity Utilities/400). The default configuration for
the FTP server is a good configuration to use. Be aware of
the fact that after the install of the TCP/IP Connectivity
Utilities/400 all of the TCP/IP servers installed with this
Page 77
Commerce Server/400 2.0 Using Commerce Server/400
option are configured to start up automatically when TCP/IP
is started on the AS/400 (STRTCP command). This is most
likely not what you would expect nor want for your machine
if it is connected to the Internet. You may want to use
option 20 on the CFGTCP menu to disable the servers that you
do not want started when TCP/IP is started. If you allow all
applications to start and run constantly, you need to be
aware of and evaluate the potential security risk involved.
In order to start the FTP server independently of the STRTCP
command you can use the STRTCPSVR SERVER(*FTP) command. The
ENDTCPSVR SERVER(*FTP) command will end just the FTP server
when you are done with it.
2.6.2.1 Transferring Content to QSYS
Once the FTP server is running on your AS/400 and client,
you are ready to connect to the AS/400 and transfer your
content. To connect to the AS/400 you will need to use your
AS/400 User ID and password when prompted. If you are going
to store all of your content in QSYS and have no binary
files to transfer, you can use the FTP connection in its
default mode. The PUT command will allow you to transfer the
files to the AS/400 and carry out the conversion from ASCII
to EBCDIC (files in the QSYS file system are stored in
EBCDIC). If you want to control the type of file the data is
stored in, the file needs to exist prior to the PUT command.
The default file type created if the file does not exist is
a physical file. If you want to store the document in a
source physical file you will need to create it prior to the
PUT command. Following is an example PUT command for the
QSYS file system:
PUT example.htm examplelib/example examplembr
The example.htm file in the current directory on the client
machine will be transferred to the examplelib library within
the example file examplembr member.
2.6.2.2 Transferring Content to Other File Systems
To work with the QDLS file system, you will need to change
naming formats. This is an AS/400 specific command that is
not common with other FTP servers. The default name format
is '0' (zero) which indicates the traditional
"LIBRARY/FILENAME MEMBER" naming method. To get to the IFS
file system and the QDLS file system within IFS, you will
need to change to naming format '1'. Issue the following
command from your FTP client: SITE NAMEFMT 1 The SITE
command tells the client this is a site specific command
that needs to be sent to the server to be carried out. Some
FTP clients do not support SITE; an alternative method will
need to be entered for these clients: QUOTE "SITE NAMEFMT
1" The quote command tells the client to send the quoted
string to the server. When the AS/400 server receives the
quoted string SITE NAMEFMT 1 it will change the naming
format used and return a status message indicating that it
Page 78
Commerce Server/400 2.0 Using Commerce Server/400
has done so. The NAMEFMT command sent without a value
following it will return the current naming form as a status
message.
Once you have changed the naming format to '1' then you can
use the IFS file naming convention to access the QDLS file
system (the entire IFS file system is available beginning
with OS/400 V3R2). The previous PUT command example would
work as follows using the naming format of '1':
PUT
example.htm/QSYS.LIB/EXAMPLELIB.LIB/EXAMPLE.FILE/EXAMPLE.MBR
The example.htm file in the current directory on the client
machine will be transferred to the examplelib library within
the example file examplembr member.
The following example shows how to get to the QDLS file
system using naming format '1'.
PUT example.htm /QDLS/example/example.htm
The example.htm file in the current directory on the client
machine will be transferred to the example folder into the
example.htm PC file. This transfer would NOT include any
ASCII conversions. The code page assignment given to the
file is the ASCII code page associated with the user profile
signed on the FTP client.
2.6.2.3 Transferring Multiple Files
The MPUT command works in the same way as the PUT command
but it gives the ability to specify wild card characters to
send multiple files with one statement, for example:
MPUT *.htm /QDLS/example/*.htm
All of the files in the current directory on the client
machine which contain the .htm extension would be
transferred to the example folder. These transfers would NOT
include any ASCII conversions. The code page assignments
given to the files are the ASCII code page associated with
the user profile signed on the FTP client. By default, the
FTP client will prompt you before transferring each file.
you can change this with the PROMPT command.
If your document root is in the root of IFS and you are
transferring files to QDLS, you will need to transfer the
files from the QDLS file system to the root file system.
This can be done through use of the WRKLNK, CPY and MOVE
commands available on the AS/400. The WRKLNK lists the files
and directories one directory at a time. It also gives you
the ability to select options (or commands) execute for the
entities within the directory. The CPY command gives you the
ability to copy files from one directory to another, or
Page 79
Commerce Server/400 2.0 Using Commerce Server/400
within the same directory with a different name. The MOVE
command provides the ability to move a file or directory
from one directory to another. The strength of the move
command is that it works on directories and all sub-
directories below the current. Note that both the CPY and
MOVE commands fail when attempting to replace an existing
file.
For more help on how to configure and use the FTP Clients
and Servers on the AS/400 refer to the AS/400 TCP/IP
Configuration and Reference (SC41-3420-02).
2.6.3 Client Access
Following are the file systems you can connect to with
Client Access:
Client Access Version Order Number File System Access
--------------------- ------------ ------------------
CA/400 for Dos Ext 5763XB1 QDLS only
CA/400 for Windows 3.1 5763XC1 IFS root
CA/400 for OS/2 5763XF1 QDLS only
CA/400 for OS/2 optimized 5763XG1 IFS root
In addition to the above versions of CA/400, there is a beta
version available at the time of this writing for Windows
95/Windows NT.
Both the QDLS connection and the IFS network drive
connection give you the ability to copy the files directly
on to the AS/400's disk. If you are using legacy clients and
your web server's document root is within any file system
other than QDLS you will need to copy or move the files to
their appropriate locations using the WRKLNK, CPY or MOVE
commands.
No data conversion takes place (EBCDIC/ASCII) during the
transfer from the client machine to the AS/400 through
either shared folders or the IFS network drive. However, a
code page assignment will be given to the file. The Client
Access product you are using decides the code page that will
be assigned. Client Access for Windows 95/NT client will
assign the code page value that your client machine is
using. The other clients will make an assignment based on
the single byte PC code page associated with AS/400 user
profile used to sign onto the shared folder or IFS network
drive.
The easiest and most secure way to determine what code page
assignment was made is to check it using the display
attributes option available on both the WRKLNK and DSPLNK
commands. If the codepage assignment is not being made
properly, you should override this value using the file
CCSID value (section 4.13.6 on page 314).
Page 80
Commerce Server/400 2.0 Using Commerce Server/400
2.6.3.1 Determining the Actual Code Page of Your Content
Depending on what client operating system you are using you
may find that the data created in a different code page than
what is assigned to it on the AS/400. If your content is
created under DOS or OS/2 then you can determine what code
page your content was created in by issuing the CHCP command
at a command prompt.
If you created the content under Windows this is a more
difficult task. In most instances, Windows uses a different
code page than DOS or any DOS session running within
Windows. The CHCP command will only tell you what your DOS
code page is not your Windows. The ANSI Code Page (ACP) is
the code page value used for the Windows interface. If you
are creating content with a Windows application your data
will potentially have a different code page than if you
created the data under DOS or OS/2. A different code page
equates to potentially different code points for the same
characters, which would produce unexpected results if not
configured properly. All Client Access clients supporting a
shared folder drive under Windows, except Client Access for
Windows 95/NT, will most likely assign an incorrect code
page to files copied to the AS/400 which were created by a
Windows program. This problem can be corrected by
configuring the File CCSID configuration value for a
directory within the directory based configuration file. The
following table should help assist in determining what CCSID
value to assign.
CCSID Windows Operating System
----- ------------------------
1250 Eastern European
1251 Cyrillic
1252 US (ANSI)
1253 Greek
1254 Turkish
1255 Hebrew
1256 Arabic
874 Thai
932 Japan
936 Simplified Chinese (PRC, Singapore)
949 Korean
950 Chinese (Taiwan, Hong Kong)
Note: Windows NT (3.5 and beyond) support Unicode data
files. It is recommended that you save any HTML files using
ANSI Code Pages instead of the Unicode code page.
Page 81
Commerce Server/400 2.0 Using Commerce Server/400
2.7 User Directories
A User Directory is a special form of a URL-path that routes
the server to a personalized location for Web documents. Any
user that has a user profile on the AS/400 can be setup to
have a their own area that contains Web content.
The URL-path that specifies a User Directory always begins
with /~ followed by a user profile. User Directory URL-paths
are always relative to the Public User Directory (section
4.14.1 on page 328) off of the user's home directory
(section 2.7.2 on page 83). The Public User Directory is a
configuration value that specifies a subdirectory where all
personal Web content is stored. Forcing this information
into a subdirectory prohibits access by the Web server to
anything in the user's home directory outside of their
Public User Directory.
User Directories are always enabled, but by default, the
Server User Profile does not have *READ authority to any
user profile so no one can take advantage of User
Directories. To enable User Directories on a person-by-
person basis, give the Server User Profile *READ access to
the person's user profile. Sign on to the system with a user
profile that has *SECADM special authority. Do a WRKOBJ
OBJ(WWW/user_profile) OBJTYPE(*USRPRF). Add the Server User
Profile (section 4.13.17 on page 324) to the list of
authorized users. Give it *USE authority. You can optionally
remove the Execute authority.
In addition, the Server User Profile (section 4.13.17 on
page 324) must have *X (Execute) authority to all
directories leading up to the user's home directory. the
Server User Profile (section 4.13.17 on page 324) should
have *RX (i.e., *USE) authority to the Public User Directory
and all Web documents in the Public User Directory. The *X
and *RX authority can be set using the WRKLNK command.
2.7.1 User Directory Example
The browser asks for http://host.name/~joe/schedule.html.
The user JOE has his home directory set to /home/joe. The
Public User Directory is set to PubHTML. The server would
find the HTML document in /home/joe/PubHTML/schedule.html.
In order for this to work, the Server User Profile (section
4.13.17 on page 324) must have at least *READ authority to
the user profile JOE, the Server User Profile must have at
least *X authority to /home/joe, and the Server User Profile
must have at least *RX authority to PubHTML/schedule.html.
Page 82
Commerce Server/400 2.0 Using Commerce Server/400
2.7.2 Home Directory
New with V3R1's Integrated File System is the concept of a
user home directory. This is an attribute of every user's
user profile. To view this setting do a DSPUSRPRF and look
under Home directory. This value defaults to the root of IFS
if the directory does not exist.
Page 83
Commerce Server/400 2.0 Using Commerce Server/400
2.8 Accessing Database Files
2.8.1 Database File Support
Database files are an integral part of the AS/400 that allow
customers to store and retrieve their mission critical data.
Database support is integrated into OS/400 through the
DB2/400 feature. Web Server/400 provides support for
returning Web content that is contained in AS/400 database
files.
Source Physical Files (section 2.8.3 on page 85)
Source physical file members are normally used to store
program source and file definitions. Source physical file
members can also be used to store Web content that is in
plain text form or marked up using HTML. Samples
(../samples/DBSample.htm#SourcePhysicalFiles) are
provided to demonstrate retrieval of documents from
source physical files.
Physical and Logical Files (section 2.8.5 on page 90)
Physical and logical files are used to store
application/business data on the AS/400. Web Server/400
supports returning formatted data (including HTML) that
is stored in keyed or non-keyed database files. The
server also supports querying data that is stored in
keyed files. Spooled files that have been copied into
database files can also be returned. Samples
(../samples/DBSample.htm#PhysicalFiles) are provided to
demonstrate retrieval of data from database files.
Distributed Data Management Files
Web content can be returned from distributed data
management (DDM) files that reference remote source
physical files, physical database files or logical
database files. Data is returned from the remote file as
if the file was located on the local system. The type of
remote file the DDM file points to determines the options
that are available.
2.8.2 Specifying keyword parameters
2.8.2.1 Using keyword parameters
Keyword parameters are used to specify special processing
for the document request. For a specific request, keywords
may be either optional or required. The keyword parameters
and values that are supported are dependent on the type of
request.
Page 84
Commerce Server/400 2.0 Using Commerce Server/400
Keyword parameters are placed at the end of the URL path
following a ? (question) mark. The value for the keyword is
place inside parenthesis.
Example using 1 keyword
http://server:port/URL-path?KWD(abc)
where,
?
indicates a keyword parameter follows.
KWD()
specifies a keyword parameter named KWD.
abc
is the keyword value.
Example using 2 keywords
http://server:port/URL-path?KWD(123)+KWD2(456+7890)
where,
?
indicates keyword parameters follow.
KWD()
specifies a keyword parameter named KWD.
123
is the KWD keyword value.
+
is a space used to separate the keyword parameters. Note
that a + (plus) sign is use to indicate spaces.
KWD2()
specifies a second keyword parameter named KWD2.
456+7890
is the KWD2 keyword value. The plus sign is converted to
a space by the server so the actual keyword value is "456
7890"
2.8.3 Accessing Source Physical Files
2.8.3.1 Specifying a URL
The general format of a URL (section 2.3 on page 53) that
accesses a source physical file (SRC-PF) member is as
follows:
Page 85
Commerce Server/400 2.0 Using Commerce Server/400
http://server:port/qsys.lib/library.lib/src.file/member
.mbr
where,
server
is the fully qualified domain name of the machine that
contains the resource.
port
is the socket port on the host machine that is running
the HTTP server. The :port is optional. If it is not
included, it defaults to port 80.
qsys.lib
indicates that the document is contained in the QSYS file
system (section 2.3.7 on page 58) on the AS/400.
library.lib
name of the library in QSYS that contains the SRC-PF.
src.file
the name of the SRC-PF contained in the above library.
member.mbr
member in SRC-PF that contains the document. If the
member is not included in the URL then the first member
will be returned unless the MBR keyword is used.
2.8.3.2 Determining Content Type
The content type (section 2.13 on page 143) indicates the
type of data that is being returned from the server to the
browser. SRC-PF members will normally contain plain text or
HTML data.
The following order is used to determine the content type of
data stored in a SRC-PF member:
. URL contains a valid content type extension (Content
Type extensions can be included on page 59)
. Member's source type is set to a valid content type
extension (e.g., HTML)
. Defaults to configured default content type (section
4.6.1 on page 271)
2.8.3.3 Authority
The server user profile (section 4.13.17 on page 324) must
have at least *USE authority to the source physical file and
library. The library containing the source physical file
must be available through the configured include libraries
(section 4.9.1 on page 292).
Page 86
Commerce Server/400 2.0 Using Commerce Server/400
2.8.3.4 Supported Keywords
The following keyword parameters (section 2.8.2 on page 84)
are supported when processing SRC-PF members:
MBR(member)
Used to specify up to 10 characters for the name of SRC-
PF member to process. The following special values can be
used:
. *FIRST - Returns the first member
. *LAST - Returns the last member
. *ALL - Returns all of the members
The member specified is case insensitive. This keyword is
ignored if the member was previously found in the URL. If
there is not a member specified in the URL then the first
member is returned.
Samples:
. MBR(SRCMBR)
. MBR(*ALL)
. MBR(*FIRST)
SENDLEN(0 | 1)
Used to specify if the content length should be sent.
Using the SENDLEN keyword overrides the send file content
length configuration value (section 4.13.10 on page 319).
Valid values are:
. '0' - Do not send content length
. '1' - Send content length
Samples:
. SENDLEN(0)
. SENDLEN(1)
Samples (../samples/DBSample.htm#SourcePhysicalFiles) are
provided to demonstrate usage of keywords when retrieving
documents from source physical files.
2.8.3.5 Restrictions
Data read from a SRC-PF member is always converted. The
retrieval of binary data (e.g., image) from a SRC-PF member
is not supported.
2.8.3.6 Examples
The following are examples of URLs that access SRC-PF
members:
http://system/qsys.lib/library.lib/source.file/member.mbr
Member source type is blank or not a valid content type
extension.
Page 87
Commerce Server/400 2.0 Using Commerce Server/400
Returns MEMBER from file LIBRARY/SOURCE as a default
content type (section 4.6.1 on page 271) document.
http://system/qsys.lib/library.lib/source.file/member.mbr
Member source type is TXT.
Returns MEMBER from file LIBRARY/SOURCE as a plain text
document.
http://system/qsys.lib/library.lib/source.file/member.mbr
Member source type is HTML.
Returns MEMBER from file LIBRARY/SOURCE as a HTML
document.
http://system/qsys.lib/library.lib/source.file/mbr.html.html
Member source type is not used to determine content type.
Returns MBR.HTML from file LIBRARY/SOURCE as a HTML
document.
http://system/qsys.lib/library.lib/source.file.html?MBR(memb
er)
Member source type is not used to determine content type.
Returns MEMBER from file LIBRARY/SOURCE as a HTML
document.
http://system/qsys.lib/library.lib/source.file
Member source type is HTML.
Returns first member from file LIBRARY/SOURCE as a HTML
document.
http://system/qsys.lib/library.lib/source.file.html?MBR(*FIR
ST)
Member source type is not used to determine content type.
Returns first member from file LIBRARY/SOURCE as a HTML
document.
http://system/qsys.lib/library.lib/source.file.txt?MBR(*ALL)
Member source type is not used to determine content type.
Returns all members from file LIBRARY/SOURCE as one plain
text document.
2.8.4 Accessing Save Files
2.8.4.1 Returning Save Files
The integrated support of save files supports the
downloading of AS/400 save files to browsers. The downloaded
Page 88
Commerce Server/400 2.0 Using Commerce Server/400
save file can then be transferred (if needed) to an AS/400
(e.g., using FTP, IFS file system) and restored.
2.8.4.2 Specifying a URL
The general format of a URL (section 2.3 on page 53) that
accesses a save file is as follows:
http://server:port/qsys.lib/library.lib/savf.file
where,
server
is the fully qualified domain name of the machine that
contains the resource.
port
is the socket port on the host machine that is running
the HTTP server. The :port is optional. If it is not
included, it defaults to port 80.
qsys.lib
indicates that the save file is contained in the QSYS
file system (section 2.3.7 on page 58) on the AS/400.
library.lib
name of the library in QSYS that contains the save file.
savf.file
the name of the save file contained in the above library.
2.8.4.3 Determining Content Type
The content type (section 2.13 on page 143) indicates the
type of data that is being returned from the server to the
browser.
The following order is used to determine the content type of
data stored in a save file:
. URL contains a valid content type extension (Content
Type extensions can be included on page 59)
. Defaults to application/octet-stream
2.8.4.4 Authority
The server user profile (section 4.13.17 on page 324) must
have at least *USE authority to the save file and library.
The library containing the save file must be available
through the configured include libraries (section 4.9.1 on
page 292).
Page 89
Commerce Server/400 2.0 Using Commerce Server/400
2.8.4.5 Restrictions
Data read from a save file is never converted. The save file
data is always returned as binary data. The content length
of the save file is always returned to the browser.
2.8.4.6 Example
The following is an example of a URL that accesses a save
file:
http://system/qsys.lib/library.lib/savf.file
Returns data from save file LIBRARY/SAVF as a
application/octet-stream document.
2.8.5 Accessing Physical and Logical Files
2.8.5.1 Specifying a URL
The general format of a URL (section 2.3 on page 53) that
accesses a physical (PF) or logical (LF) database file is as
follows:
http://server:port/qsys.lib/library.lib/db.file/member.
mbr
where,
server
is the fully qualified domain name of the machine that
contains the resource.
port
is the socket port on the host machine that is running
the HTTP server. The :port is optional. If it is not
included, it defaults to port 80.
qsys.lib
indicates that the data is contained in the QSYS file
system (section 2.3.7 on page 58) on the AS/400.
library.lib
name of the library in QSYS that contains the database
file.
db.file
the name of the PF/LF contained in the above library.
member.mbr
member in PF/LF that contains the document. If the member
is not included in the URL then the first member will be
returned unless the MBR keyword is used.
Page 90
Commerce Server/400 2.0 Using Commerce Server/400
2.8.5.2 Determining Content Type
The content type (section 2.13 on page 143) indicates the
type of data that is being returned from the server to the
browser. Database files will normally contain plain text or
HTML data. If the request's content type is plain text then
the data by default is formatted by the server into columns
with column headings.
The following order is used to determine the content type of
data stored in a database file:
. URL contains a valid content type extension (Content
Type extensions can be included on page 59)
. Defaults to plain text content type
2.8.5.3 Authority
The server user profile (section 4.13.17 on page 324) must
have at least *USE authority to the database file and
library. The library containing the database file must be
available through the configured include libraries (section
4.9.1 on page 292).
2.8.5.4 Supported Keywords
The following keyword parameters (section 2.8.2 on page 84)
are supported when processing database files:
HEADER([library/]src-pf member[.html])
Used to specify a header document to include before the
database data. A header can be used to set the document
title and describe the database data that follows.
The first part of the header keyword value indicates the
source physical file that contains the member containing
the header information. Optionally, the source physical
file can be pre-pended with the library containing the
source physical file. The slash separating the library
and src-pf should be escaped (e.g., / = %2F). The library
specified must be accessible through the configured
include libraries (section 4.9.1 on page 292). If the
library is not specified then the header source physical
file must reside in the same library as the PF/LF that is
being processed.
The second part specifies which member contains the
header data. The data contained in the member is assumed
to be plain text unless one of the following two methods
is used to indicate the member contains HTML data:
1. .HTML is appended to the member name
2. Member type is set to HTML
Samples:
. HEADER(SRCFILE+HEADERMBR)
Page 91
Commerce Server/400 2.0 Using Commerce Server/400
. HEADER(SRCFILE+HEADER.HTML)
. HEADER(LIBRARY/SRCFILE+HEADERMBR)
. HEADER(LIBRARY%2FSRCFILE+HEADER.HTML)
FOOTER([library/]src-pf member[.html])
Used to specify a footer document to include after the
database data. A footer can be used to display summation
information.
The first part of the footer keyword value indicates the
source physical file that contains the member containing
the footer information. Optionally, the source physical
file can be pre-pended with the library containing the
source physical file. The slash separating the library
and src-pf should be escaped (e.g., / = %2F). The library
specified must be accessible through the configured
include libraries (section 4.9.1 on page 292). If the
library is not specified then the footer source physical
file must reside in the same library as the PF/LF that is
being processed.
The second part specifies which member contains the
footer data. The data contained in the member is assumed
to be plain text unless one of the following two methods
is used to indicate the member contains HTML data:
1. .HTML is appended to the member name
2. Member type is set to HTML
The footer should not include either the or
tag.
Samples:
. FOOTER(SRCFILE+FOOTERMBR)
. FOOTER(SRCFILE+FOOTER.HTML)
. FOOTER(LIBRARY/SRCFILE+FOOTERMBR)
. FOOTER(LIBRARY%2FSRCFILE+FOOTER.HTML)
HEADINGS(0 | 1)
Used to specify if column headings should be included in
the formatted output. Valid values are:
. '0' - Do not include column headings
. '1' - Include column headings
If the HEADINGS keyword is not specified then by default
column headings are included if the data being returned
is plain text. Note that column headings can only be
included when the content type is plain text.
Samples:
. HEADINGS(0)
. HEADINGS(1)
Page 92
Commerce Server/400 2.0 Using Commerce Server/400
KEY(value)
Used to specify a key value when reading a keyed database
file. The length of the key value must be less than or
equal to the file's key length. If the key value's length
is less than the file's key length then key matches will
be performed on the key value's length number of
characters. The value specified is case sensitive.
Hexadecimal characters can be included in the key by
enclosing the hex characters as follows: X'chars' or
x'chars' (e.g., X'00010A' which is converted to the 8-bit
binary values 0,1,10 which equals 266 decimal). Hex
characters can be used to search files that have numeric
keys, although care must be taken to ensure the hex value
matches the storage method used for the numeric field.
Both character and hexadecimal values can be included in
the key value.
The key value is combined with the KEYOPT (KEYOPT on page
93) keyword when processing the file. If the file is
keyed and no key is specified then all records are
returned.
Samples:
. KEY(AAA)
. KEY(X'0000001F')
. KEY(X'F1F2F3F4'ABC)
KEYOPT(option)
Used to specify a 2 character processing option when
reading a keyed database file. The KEYOPT determines how
the specified key value is compared with the file's key.
Valid values are:
. EQ - Return records with a key equal
. GE - Return records with a key greater than or equal
. GT - Return records with a key greater than
. LE - Return records with a key less than or equal
. LT - Return records with a key less than
The value specified is case insensitive. If a key option
is not specified and a key is specified then the key
option defaults to EQ.
Samples:
. KEYOPT(EQ)
. KEYOPT(GE)
. KEYOPT(LT)
KEY2(value)
Used to specify a secondary key value when reading a
keyed database file. A secondary key value cannot be
specified if the KEYOPT (KEYOPT on page 93) is set to EQ.
Specifying two keys allows for a range of records to be
Page 93
Commerce Server/400 2.0 Using Commerce Server/400
returned. The following types of searches can be
performed using 2 keys:
. KEY < File Key < KEY2
. KEY < File Key <= KEY2
. KEY <= File Key < KEY2
. KEY <= File Key <= KEY2
See the KEY (KEY on page 93) keyword parameter
description for more information on using key values. The
key 2 value's length does not have to match the first key
value's length. The key 2 value is combined with the
KEYOPT2 (KEYOPT2 on page 94) keyword when processing the
file.
Samples:
. KEY2(BBB)
. KEY2(X'0000009F')
. KEY2(X'F1F2F3F9'ABC)
KEYOPT2(option)
Used to specify a 2 character processing option when
reading a keyed database file with 2 keys. See the KEY2
(KEY2 on page 93) keyword parameter description above for
more information on using 2 keys to search a keyed file.
The KEYOPT2 determines how the specified key 2 value is
compared with the file's key. Valid values are dependent
on the value of the KEYOPT (KEYOPT on page 93) keyword
parameter:
KEYOPT is set to LE or LT, KEYOPT2 must be either:
. GE - Return records with a key greater than or equal
. GT - Return records with a key greater than
KEYOPT is set to GE or GT, KEYOPT2 must be either:
. LE - Return records with a key less than or equal
. LT - Return records with a key less than
The value specified is case insensitive. KEYOPT2 must be
specified if the KEY2 keyword parameter is specified.
Samples:
. KEYOPT2(GT)
. KEYOPT2(LE)
COLUMNS(['prefix']numbers['suffix'])
Used to specify which columns/fields are to be returned
from the database file. The columns also determine the
order of the returned columns.
Optionally, a prefix can be added before the column(s)
and a suffix can be added after the column(s). The prefix
and suffix are text strings contained in single quotes
that are outputted before and after the column(s)
Page 94
Commerce Server/400 2.0 Using Commerce Server/400
respectively. To insert a single quote specify two single
quotes (e.g., a prefix of '''' would output one single
quote). The column prefix and suffix text is never
escaped. In most cases, column headings (HEADINGS on page
92) should be turned off when using prefixes and
suffixes.
If multiple columns are to be returned then each column
number must be separated by commas. A range of columns
can be specified by separating two column numbers with a
hyphen.
The SPACING (SPACING on page 95) keyword can be used to
control spacing between columns.
Valid column numbers range from 1 to 256. Columns can be
returned more than once. If COLUMNS is not specified then
all columns will be returned in the file's order.
Samples:
. COLUMNS(1)
. COLUMNS(''1'')
. COLUMNS(2,5)
. COLUMNS(''2'',''''5'''')
. COLUMNS(3,2,3)
. COLUMNS(3,'',3'') Note: %22 =
"
. COLUMNS(2-4)
. COLUMNS(''2-4'')
. COLUMNS(10-6,12)
SPACING(column.spacing)
Used to specify the spacing before each column that is
being returned from the database file. The COLUMNS
(COLUMNS on page 94) keyword can be used to control which
columns are returned and add text before and/or after the
columns.
Column spacing is specified by a column number and a
spacing value that are separated by a period. Spacing for
multiple columns must be separated by commas. A spacing
value for a range of columns can be specified by
separating two column numbers with a hyphen followed by
the period and the spacing value.
Valid column numbers range from 1 to 256. Valid spacing
values are from 0 to 256. If SPACING is not specified for
a column then there will be no spaces before the first
column and one space between each additional column. If
multiple values are given for a single column the last
once encountered will be used.
Samples:
Page 95
Commerce Server/400 2.0 Using Commerce Server/400
. SPACING(1.10) - Inserts 10 spaces before the 1st
column
. SPACING(2.5,5.3) - Inserts 5 spaces before the 2nd
column and 3 spaces before the 5th column
. SPACING(6-10.2,2.0) - Inserts 2 spaces before
columns 6 through 10 and no spaces before column 2
NOESCAPE(numbers)
Used to specify which columns/fields data should not be
escaped. By default the characters '<', '>' and '&' are
escaped so the browser does not interpret the column as
containing HTML tags. If the column does contain HTML
tags then this keyword tells the server not to escape the
special characters in the column's data.
Multiple columns can be specified by separating each
column by commas. A range of columns can be specified by
separating two column numbers with a hyphen.
Valid column numbers range from 1 to 256. This keyword
effects only character fields.
If the content type is not plain text then by default
none of the fields are escaped and specifying the
NOESCAPE keyword will instruct the server to escape the
specified values.
Samples:
. NOESCAPE(1)
. NOESCAPE(2,5)
. NOESCAPE(3,2,3)
. NOESCAPE(2-4)
. NOESCAPE(10-6,12)
SPLF(0 | 1)
Used to specify that the database file contains a spooled
file. The spooled file data must have been copied into
the database file with the CTLCHAR(*PRTCTL) option on the
CPYSPLF command. Valid values are:
. '0' - Output the spooled file as pre-formatted data.
This option uses a fixed font which maintains
columns.
. '1' - Output the spooled file as formatted data.
This option uses a variable font and should only be
used when the spooled file does not contain columns.
If the line spacing is not correct it is because the
browser being used does not support multiple line
breaks.
If the URL indicates the database file contains HTML
spooled file data then either option can be specified and
the data is returned as is from the database file. Non-
Page 96
Commerce Server/400 2.0 Using Commerce Server/400
text content types will return the spooled file data with
the printer control characters.
The following keywords are ignored when this keyword is
used:
. HEADINGS - Column headings are never returned for
spooled files.
. KEY, KEYOPT, KEY2 and KEYOPT2 - Key processing is
not supported.
. COLUMNS and SPACING - All columns are returned. The
first 4 characters which contain control information
are not returned.
. NOESCAPE - All special characters are escaped unless
the data being returned is identified as HTML.
Data can also be returned directly from spooled files
(section 2.10 on page 134).
Samples:
. SPLF(0)
. SPLF(1)
PAGES(start-end)
Used to specify which spooled file pages are to be
returned.
The format of the PAGES keyword value is the starting
page number followed by a hyphen and then the ending page
number. If the starting page number is greater then the
total number of spooled file pages then no spooled file
data is returned. The ending page number may be set to
the special value *LAST. The starting and ending page
values are inclusive.
If PAGES is not specified then all of the pages will be
returned.
Samples:
. PAGES(1-*LAST)
. PAGES(10-*LAST)
. PAGES(5-8)
MBR(member)
Used to specify up to 10 characters for the name of PF/LF
member to process. The following special values can be
used:
. *FIRST - Returns the first member
. *LAST - Returns the last member
. *ALL - Returns all of the members
The member specified is case insensitive. This keyword is
ignored if the member was previously found in the URL. If
Page 97
Commerce Server/400 2.0 Using Commerce Server/400
there is not a member specified in the URL then the first
member is returned.
Samples:
. MBR(DBMBR)
. MBR(*ALL)
. MBR(*FIRST)
RECFMT(format)
Used to specify up to 10 characters for the name of LF
record format to process. The format specified is case
insensitive. If there is not a record format specified in
the URL then the first record format is processed.
Samples:
. RECFMT(RCDFMT1)
. RECFMT(RCDFMT2)
SENDLEN(0 | 1)
Used to specify if the content length should be sent.
Using the SENDLEN keyword overrides the send file content
length configuration value (section 4.13.10 on page 319).
Valid values are:
. '0' - Do not send content length
. '1' - Send content length
Samples:
. SENDLEN(0)
. SENDLEN(1)
Samples (../samples/DBSample.htm#PhysicalFiles) are provided
to demonstrate usage of keywords when retrieving data from
database files.
2.8.5.5 Output Considerations
Requests for plain text data from database files results in
the data being formatted by the server and returned as pre-
formatted HTML data. If the data is identified as any other
type of data (e.g., HTML data) the database file data is not
formatted with HTML tags. The following lists different
formatting considerations:
Columns/Fields returned
The COLUMNS (COLUMNS on page 94) keyword parameter can be
used to control which fields are returned and the order
of the fields. The COLUMNS keyword can also be used to
add text before and/or after the column. The SPACING
(SPACING on page 95) keyword can be used to control
column spacing.
Page 98
Commerce Server/400 2.0 Using Commerce Server/400
Column/Field justification
Numeric data is always right-justified and all other data
is left-justified. If the maximum width of the formatted
data is less than half the width of the column heading
then the formatted data is centered under the column
heading.
HTML tags
When returning plain text from a database file, if a
field/column contains HTML tags then the NOESCAPE
(NOESCAPE on page 96) keyword must be used to inform the
server that it should not escape the special characters
'<', '>' and '&'.
The HTML "wrapper" tags are included or excluded based on
the content type (Determining Content Type on page 91) of
the document/database file and the content type of the
optional header (HEADER on page 91). The HTML "wrapper"
tags consist of:
. ,
. ,,,
. ,
The HTML "wrapper" tags are included in the following
scenarios:
1. No header and database contains plain text
2. Plain text header and database contains plain text
3. Plain text header and database contains HTML
The HTML "wrapper" tags are not included in the following
scenarios:
1. No header and database contains HTML
2. HTML header and database contains plain text
3. HTML header and database contains HTML
Edit codes and edit words
If a field that is being returned has an edit code/word
the edit code/word is used to format the returned data.
If the field does not have an edit code/word and the
field is numeric then EDTCDE(1) is used. Hexadecimal data
is always formatted as X'xxxxxx'.
Column headings
The text for the column heading is determined by the
field definition. The first available of the following
field values determines the column heading text:
. Column heading (i.e., COLHDG DDS keyword specified)
. Text (i.e., TEXT DDS keyword specified)
. Field name
Column headings can be turned off or on using the
HEADINGS (HEADINGS on page 92) keyword parameter. The
HEADER (HEADER on page 91) keyword parameter can be used
to return customized column headings.
Page 99
Commerce Server/400 2.0 Using Commerce Server/400
Document Title
If there is not an HTML header the title of the document
returned is set to the second-level message text of
message ID (WWW0911 - normal database output, WWW0913 -
formatted spool file output, or WWW0914 - pre-formatted
spool file output) in the WWWMSGF message file. If a
different default title is desired then change the
second-level message text. If a customized title is
required then include a HTML header using the HEADER
(HEADER on page 91) keyword parameter.
NULL values
NULL field values are supported. If the field contains a
NULL value then the second-level message text of message
ID WWW0910 in the WWWMSGF message file is the value that
is returned. The default value shipped is '*NULL'. If
spaces are desired then change the '*NULL' value to ' '.
If the formatted width is shorter than the message text,
only the formatted width number of characters are
returned (e.g., formatted width = 2 then *N would be
returned).
Variable length fields
Variable length fields are supported. The width of the
column is the maximum length of the variable length
field.
2.8.5.6 Restrictions
Information can only be returned from one database file. If
the data desired is contained in multiple files then a
script (section 2.9 on page 102) will have to be written.
Data read from a database file is always converted. The
retrieval of binary data (e.g., image) from a database file
is not supported.
2.8.5.7 Examples
The following are examples of URLs that access database
files:
http://system/qsys.lib/library.lib/database.file
Formats and returns all the fields of the first member in
file LIBRARY/DATABASE. All records are returned.
http://system/qsys.lib/library.lib/database.file.html
Returns all the fields of the first member in file
LIBRARY/DATABASE. No formatting is done. All records are
returned.
Page 100
Commerce Server/400 2.0 Using Commerce Server/400
http://system/qsys.lib/library.lib/keyed.file?KEY(AA)+KEYOPT
(GT)+KEY2(AD)+KEYOPT2(LE)
Formats and returns all the fields of the first member in
file LIBRARY/KEYED. Only records that have a key greater
than AA and less than or equal to AD are returned.
http://system/qsys.lib/library.lib/keyed.file?COLUMNS(3,1)+S
PACING(3.10)+HEADINGS(0)+HEADER(SRCPF+HEADER.HTML)+FOOTER(SR
CPF+FOOTER)+KEY(X'0000001F')
Formats and returns the 3rd and 1st column/field of the
first member in file LIBRARY/KEYED. Ten spaces are
inserted before column 3. No column headings are
returned. A HTML header and footer (footer's member type
is HTML) is included in the output. Only records that
have key equal to packed decimal 1 are returned.
Page 101
Commerce Server/400 2.0 Using Commerce Server/400
2.9 CGI Scripts
2.9.1 Flow of a CGI Script
An overview of the interactions of clients, servers, and
scripts might be helpful. This overview is based on the
following example. A company's Web site provides a Web page
that gives a short survey to anyone who accesses their site.
The survey asks two questions:
1.Do you prefer to see images on Web pages?
2.On Web pages with images, do you prefer GIF or JPEG
images?
Each person that responds gets added to a database and the
current percentages of answers to each question are then
returned to the customer's browser.
Now might be a good time to give this sample a try.
What happened when you submitted your answers to the survey?
Many things. The above link brought up the HTML document
/samples/scripts.htm. This document contained introductory
text plus an HTML form. An HTML form
(http://www.ncsa.uiuc.edu/SDG/Software/Mosaic/Docs/fill-out-
forms/overview.html) consists of special markup that allows
for user input to be gathered by the browser and sent back
to a script on the Web server.
After the Web document was displayed, you made your survey
selections and pressed the "Submit" button. Doing this
caused the browser to gather your answers and submit another
request to the Web server. This request consisted of a URL
that pointed to a specific script (which was listed in part
of the special HTML form markup), along with the data
gathered from the HTML form.
The Web server then received the script URL and the form
data. The server set up some data structures and called the
script program. The script made several calls to Application
Program Interfaces (APIs) supplied by Web Server/400. These
APIs provided the script with the form data and many pieces
of data relating to the request. The script wrote out the
form data to a database and tallied the current percentages.
The script then dynamically created an HTML page. This HTML
data was relayed to the Web server through other Web
Server/400 APIs. The script program then ended. When the
script ended, control was passed back to the Web server to
finish the request. The Web server then sent back to the
browser all the data dynamically created by the script. The
Page 102
Commerce Server/400 2.0 Using Commerce Server/400
browser then received the Web page consisting of the new
survey results and displayed it.
The above steps can be summarized by the following:
1.Display initial HTML form.
2.User fills in form and submits the request.
3.Browser requests the script URL and provides the form
data.
4.Server receives request and prepares script input data.
5.Server calls script program.
6.Script receives input from Web Server/400 APIs.
7.Script performs any useful processing.
8.Script prepares its output.
9.Script returns its output to the server through Web
Server/400 APIs.
10. Script program ends.
11. Server sends back the script output to the
browser.
12. Browser displays new output.
2.9.2 Script Concepts
The sections below cover script creation and the
interactions between the Web server, the browser, and a CGI
script.
CGI Environment Variables (section 2.9.3 on page 104)
The request headers sent by the browser are communicated
to the script through a set of pre-defined and browser-
specific pseudo-environment variables.
Script Inputs (section 2.9.4 on page 107)
Input to a script is received through environment
variables, standard input, or command-line arguments.
Script Outputs (section 2.9.5 on page 110)
A script can send data and instructions back to the
browser through response headers and the object body.
Script APIs (section 2.9.7 on page 115)
Web Server/400 supplies a set of Application Program
Interfaces (APIs) that allow user-written scripts to
interact with the Web server to successfully handle an
HTTP request.
Creating a Script Program (section 2.9.8 on page 130)
Some special instructions need to be followed to make
your script available to browsers and to make it function
properly.
Page 103
Commerce Server/400 2.0 Using Commerce Server/400
2.9.3 CGI Environment Variables
Once the Web server calls the script, a mechanism is needed
for the two processes to communicate. Part of this
communication is done through pseudo-environment variables.
Before the Web server calls the script, the server creates
several pseudo-environment variables from the request
headers sent by the browser and some server configuration
values. These variables have a name and a string value. The
script references the variables by name to obtain their
value.
The reason these variables are called pseudo-environment
variables is because the AS/400 doesn't have Unix-style
process environment variables. Instead, Web Server/400
simulates this environment and provides an API to access the
variable from scripts.
Listed below are all the environment variables set prior to
calling a script. Any of these can be accessed by making an
API call with the name of the environment variable passed in
as one of the parameters.
2.9.3.1 Server Supplied
The following environment variables are specific to the Web
server or are configurable by the administrator of the Web
server.
GATEWAY_INTERFACE
The GATEWAY_INTERFACE is the name and version of protocol
that is in use for calling scripts. The format is
Name/Version. This is currently CGI/1.1.
SERVER_NAME
The SERVER_NAME is the TCP/IP host name of the AS/400
currently running the Web server. This is either obtained
from the machine or configured using the Server Host Name
(section 4.13.13 on page 321) configuration directive. For
example, this might be www.inetmi.com.
SERVER_PORT
The SERVER_PORT is the TCP/IP socket port the Web server is
currently using to communicate with browsers. It is a
character string representation of the port number in
decimal. For example, by default this is 80-the well known
port for HTTP.
SERVER_SOFTWARE
The SERVER_SOFTWARE is a product specific string that
identifies the name of the Web server currently running and
the version of that server. For Web Server/400, this value
is WebServer400/1.3. For Commerce Server/400, this value is
CommerceServer400/1.0.
Page 104
Commerce Server/400 2.0 Using Commerce Server/400
2.9.3.2 Browser Supplied
AUTH_TYPE
This is the string that identifies the type of user
authentication being used by the browser for this request.
If the AUTH_TYPE is set, the HTTP_AUTHORIZATION environment
variable should also be set. This has the form auth_type:
auth_data. The auth_type is the same as the AUTH_TYPE
environment variable. The auth_data is the authorization
type specific data.
CONTENT_LENGTH
This is the length, in bytes, of the request body that
follows the header. In the case of a POST method, this
indicates the length of the form data that is sent by the
browser. If this isn't set or is zero, then the browser only
sends request headers.
CONTENT_TYPE
This is the content type (section 2.13 on page 143) of
request body sent by the browser.
PATH_INFO
PATH_INFO is the rest of the URL-path after the script name.
For example, if /cgi-bin/cgitest/extra/path was entered,
PATH_INFO would be set to /extra/path. This value is also
completely unescaped as well. This does not include the
query string.
PATH_TRANSLATED
PATH_TRANSLATED is similar to PATH_INFO except the extra
path is transformed as if it were entered as the URL-path by
itself. Alias substitution, user directory handling, and so
forth are all performed on this value. If the extra path is
not valid or doesn't exist after this transformation, the
PATH_TRANSLATED is set to the PATH_INFO subdirectory of the
Document Root of the Default Source Type. For example, if
/cgi-bin/cgitest/samples/ is entered, the Default Source
Type is *Root, and the Document Root is /WWWServ/WebDocs/,
then the PATH_TRANSLATED would be set to . If /cgi-
bin/cgitest/~WWWUSER/ is entered, PATH_TRANSLATED would be
/WWWServ/WWWUser/PubHTML/ (assuming WWWUSER's home directory
is /WWWServ/WWWUser/).
QUERY_STRING
The QUERY_STRING is everything entered after a question mark
("?") in the URL. This data is not converted at all. The
leading question mark is not included. For example, if the
user enters a URL of /cgi-
bin/cgitest?this+is+a+query+string, QUERY_STRING would be
set to this+is+a+query+string.
Page 105
Commerce Server/400 2.0 Using Commerce Server/400
REMOTE_ADDR
This is the IP address of the browser in dotted decimal
notation. This is always available. For instance, this might
be 12.34.56.78.
REMOTE_HOST
This is the host name of the browser making the request. If
this cannot be obtained, it is not set. For example, this
might be joe.company.com.
REMOTE_USER
This is the user name used to authenticate requests to the
server. This is set to the user portion of the Authenticate
request header. If this header is not sent, this variable is
not set.
REMOTE_PASSWORD_MD5
This is a hashed version of the password used to
authenticate requests to the server. The password portion of
the Authenticate request header is hashed using the MD5(*)
algorithm. This algorithm creates a message digest of the
password. The vital property of this function is that it is
very difficult to obtain the original value (the password)
if you only know the message digest. This means the
REMOTE_PASSWORD_MD5 value does not have to be protected to
maintain the integrity of a user's password. If Authenticate
the header is not sent, this variable is not set.
(*)Derived from the RSA Data Security, Inc. MD5 Message-
Digest Algorithm.
REQUEST_METHOD
This is the HTTP method of the URL request made by the
browser. Some valid methods are GET, POST, and PUT.
SCRIPT_NAME
This is the name of the currently running script, as it is
known by browsers. The name is escaped and does not include
any of the PATH_INFO or query strings. For example, the
script /cgi-bin/cgitest/extra/path would have a SCRIPT_NAME
of /cgi-bin/cgitest.
SERVER_PROTOCOL
The SERVER_PROTOCOL is the version of HTTP that is being
used for this request. This can be either HTTP/0.9 or
HTTP/1.0. HTTP/0.9 is only used if the browser has indicated
to use that version.
Other Request Headers
All other request headers that are sent by the browser are
made available to the script through environment variables.
Each header has a prefix of HTTP_ added to the header name.
Any dashes ("-") in the header name are changed to
underscores ("_"). If the same header appears more than
Page 106
Commerce Server/400 2.0 Using Commerce Server/400
once, a comma separated list of each of the header's values
is created. For example, the header User-Agent:
NeatBrowser/1.0 would result in an environment variable of
HTTP_USER_AGENT with a value of NeatBrowser/1.0. Another
example is receiving the headers Accept: text/html and
Accept: text/plain. This would result in one environment
variable named HTTP_ACCEPT with a value of text/html,
text/plain.
The additional scripts (/shipped/samples/cgitest.sht) sample
page shows examples of retrieving environment variables from
different programming languages.
2.9.4 Script Inputs
2.9.4.1 Overview
A user-written CGI script can get input from a variety of
sources. All of these sources are reached by the script
either through the Web Server/400 Get Environment Variable
API (Get Environment Variable on page 124) or Read API.
Possible sources of input are any of the pseudo-environment
variables, the standard input, or the command line
parameters.
2.9.4.2 Input Sources
Environment Variables (section 2.9.3 on page 104)
The environment variables make various server-specific
and request-specific values available to the script. The
main two sources of input provided by the environment
variables are the QUERY_STRING and PATH_INFO (PATH_INFO
on page 105).
Standard Input
The standard input is a Unix term adopted by CGI to
indicate a stream file that any process can read to get
input. Generally, in the Unix environment this input is
piped to a program by the command processor or another
program. Through Web Server/400's CGI support, standard
input is made available to scripts through two Web
Server/400 APIs: Read (Read on page 121) or Get Form
Variable. Get Form Variable is a high-level function that
hides where the actual input is coming from.
What is received by the script through standard input?
Most browsers currently in use only use standard input to
send to the script the user-entered HTML form data. This
is done when the form is submitted using the POST method.
The less common PUT method also provides data to a script
over standard input. The HTML form data is sent by the
browser to the server in the request body. The request
body usually has a content type of application/x-www-
Page 107
Commerce Server/400 2.0 Using Commerce Server/400
form-urlencoded. If this is the content type of the
request body, the server automatically converts the form
data into EBCDIC before providing it to the script.
If another content type is provided by the browser, then
no conversion takes place and it is up to the script
program to perform its own conversions. This would make
it possible for a script to accept a multi-part document
as form input. Since each part could require a different
type of conversion (or no conversion at all), having the
server blindly convert everything wouldn't work in these
cases.
Command Line Parameters
Scripts usually do not receive any command line
parameters. The only case that they do have command line
parameters is when a Query String is entered as part of
the URL for the script and the Query String does not have
an equal sign ("=") in it. When a Query String without
equal signs is supplied, the Query String is split-up and
passed in as command line parameters. The Query String is
separated into plus ("+") divided words, each word being
passed in as a separate parameter. The Query String is
not escaped prior to turning it into parameters. The
reason a plus ("+") separates the parameters is because
all spaces in a Query String should be escaped to pluses
prior to making a request.
For example, if the URL /cgi-
bin/cgitest?This+Isn't+%41+Big+Deal is requested, the
Query String would be passed into the script as command
line parameters:
CALL WWWCGI/CGITEST PARM('This' 'Isn''t' '%41' 'Big'
'Deal')
Notice that the capital "A" is passed in escaped to hex
41 ("%41") which is the ASCII code point for that letter.
The Web Server/400 API UnEscape Read Data (UnEscape Read
Data on page 126) can be used to unescape this data to an
EBCDIC string.
Note: Command line parameters to scripts written in
REXX/400 are slightly different. These parameters are not
separated into multiple parameters but are sent in as one
single parameter. Any pluses ("+") are converted to
spaces first.
2.9.4.3 Request Methods
The HTTP method used to make the request indicates to the
server where to receive its input. Possible methods are GET,
HEAD, POST, PUT, DELETE. The method can be obtained by
calling the Get Environment Variable (Get Environment
Page 108
Commerce Server/400 2.0 Using Commerce Server/400
Variable on page 124) Web Server/400 API with a variable
name of REQUEST_METHOD.
GET
The GET method is the most common and default method used
by browsers. This tells the Web server that the browser
is requesting a document to be returned. Scripts can also
be performed with a GET. A script that is requested with
a GET receives its input through a query string. Standard
input is not sent by the browser.
HEAD
The HEAD method performs the same way as a GET except
that only the response headers are sent back. The object
body is not sent. If a script is called with the HEAD
method, it should not send back an object body.
POST
The POST method is normally used for an HTML form. This
is similar to a GET except that the form input data is
send through standard input to the script instead of
using the query string.
PUT
The PUT method is the same as the POST except that the
PUT can be used to indicate a different mode of
operation. The PUT usually implies that the operation
should take effect immediately whereas the POST's action
might be delayed.
DELETE
The DELETE method can be used to instruct a script to
remove some entity instead of creating something like
POST and PUT imply.
2.9.4.4 Seeing Script Inputs in Action
A standard script for every platform is one that displays
all the script inputs. The CGITEST script returns the
command line arguments, a query string, extra path
information, standard input, all the standard environment
variables, and some of the browser header fields. The ILE
C/400 source for this is also available. Select any of the
following URLs to see the various script inputs in action.
. /cgi-bin/cgitest (/cgi-bin/cgitest)
This is the straightforward display with nothing fancy
going on.
. /cgi-bin/cgitest/extra/path/info (/cgi-
bin/cgitest/extra/path/info)
Page 109
Commerce Server/400 2.0 Using Commerce Server/400
Notice the PATH_INFO and PATH_TRANSLATED environment
variables.
. /cgi-bin/cgitest?query+string (/cgi-
bin/cgitest?query+string)
Notice the QUERY_STRING environment variable.
. /cgi-bin/cgitest?VarName=value=another+value (/cgi-
bin/cgitest?VarName=value&AnotherVar=another+value)
This is what HTML form data would look like on a form
that does a GET.
See also the script samples (/shipped/samples/script.htm)
and additional scripts (/shipped/samples/cgitest.sht) for
more script examples in additional programming languages.
2.9.5 Script Outputs
2.9.5.1 Overview
Returning viewable data to a browser at the end of
processing a script is not required. However, all practical
scripts return some sort of output. This output might be
something the browser displays, such as a dynamically
created HTML document, or it might be a response header that
redirects a browser to another URL.
Even if a script only adds a record to a database or creates
a new stream file, outputting a confirmation back to the
user is usually expected. Also, if something goes wrong, a
helpful error message can be returned to the browser for
display.
HTTP provides two ways to return output to a browser. One
way is to send back pre-defined response headers that will
modify the browser's behavior. Another is to send back an
object body that the browser displays to the user. Both of
these outputs are sent back through standard output.
Standard output is a Unix term adopted by CGI to indicate a
stream file that any process can write its output to. In
Unix environments, standard output is generally redirected
to a file or to another program. Through Web Server/400's
CGI support, standard output is made available to scripts
through the Write (Write on page 122) Web Server/400 API.
2.9.5.2 Structure of a Response
The Hypertext Transfer Protocol defines the structure a
script needs to follow in order to communicate properly with
a browser. The Web server assists the script in following
this structure unless the script wants to handle everything
(NPH Scripts on page 113).
Page 110
Commerce Server/400 2.0 Using Commerce Server/400
The basic structure is fairly simple. A script's response
should begin with any response headers (Response Headers on
page 111) that it chooses to return. This is followed by a
blank line (Response Header Format on page 111) (i.e., a
line containing only a carriage return and linefeed). After
the blank line, the object body is returned. The object body
is usually what is displayed by the browser. In an older
HTTP/0.9 version transaction, only the object body is
returned and the response header is completely skipped.
However, no matter which version of HTTP is being used, a
script must always return a response header (even if it is
an empty header). This header is not passed on to the client
by the Web server if HTTP/0.9 is being used.
2.9.5.3 Response Headers
Response headers are the first thing a server sends back to
a browser to satisfy a request. This information is
generally not displayed to the user. The response headers
are used to describe the Web server to the browser, to
describe what the server is sending back, and to inform the
browser of anything it needs to do.
A complete specification of the response headers in HTTP/1.0
is available from IETF
(http://www.w3.org/hypertext/WWW/Protocols/HTTP1.0/draft-
ietf-http-spec.html). An overview of their use is provided
below.
Response Header Format
The Response Header is a line oriented data stream that
begins with the first line of output by the script. It
continues until the first blank line. All response header
data is in US-ASCII (which is essentially character set
850).
The format of all response headers is:
Header-Name: Header-Value
where,
Header-Name
A string that identifies the header. This generally has a
descriptive name where each word is separated by a dash
("-"). Many Header-Names are pre-defined.
Header-Value
After a colon (":") and a space, the value of the
response header is included. This is a text string that
represents the current value for the specified header.
The Header-Value is terminated with a carriage return and
Page 111
Commerce Server/400 2.0 Using Commerce Server/400
linefeed. Some headers require a list of data to be
returned. Lists are composed of comma and space separated
text strings. Most pre-defined response headers have a
well-defined Header-Value.
All header lines end with a US-ASCII carriage return and
linefeed. These are code points 13 and 10 decimal in
character set 850, respectively. A line with just these
two characters on it ends the response header section.
Common Response Headers
Any valid response header can be sent back by a script. Some
are handled specially by the Web server to fill header
values that the server normally returns. Other headers are
almost always returned by the Web server whether they are
specified by the script or not. The following response
headers are the more popular and useful headers used by
scripts. Any header not known by the Web server is directly
passed on to the browser.
Status
The Status header is a special header that is intercepted
by the Web server to determine what type of status line
should be sent back to the browser. The format of this is
Status: XXX Reason-Phrase, where XXX is a valid numeric
Status Code (section 2.9.6 on page 114) that indicates
the success, failure, or special action of the request
and Reason-Phrase is a text description of how the
request turned out. The number is for computers to use
and the text is for humans to use.
Content-Type
The Content-Type header indicates what type of data is
being returned to the browser in the object body. The
format of this header is Content-type: Type/Subtype,
where Type and Subtype follow the rules for MIME types
(section 2.13 on page 143). If an object body is being
returned, this header should be set. Typically, this is
set to either text/html or text/plain.
Content-Length
The Content-Length header indicates to the browser how
much data, in bytes, is being returned in the object
body. This count does not include the response headers or
the blank line that ends the response headers. If this is
not included, the browser will read data until the Web
server closes the connection. Note that the script does
not have the ability to close the connection (nor should
it need to). The format of this header is Content-length:
X, where X is the number of bytes in decimal being
returned.
Page 112
Commerce Server/400 2.0 Using Commerce Server/400
Location
The Location header indicates to the Web server that
instead of relying on the script to create an object
body, the Web server should redirect the browser to the
URL specified as a parameter to this header. The format
of this header is Location: URL, where URL is either a
fully qualified URL (Uniform Resource Locator on page 53)
or a fully qualified path that specifies a URL on the
current Web server. The browser will retrieve and display
this other URL to satisfy this request.
NOTE: Web Server/400 deviates slightly from the CGI
standard when handling the Location header. The standard
says that if the URL specified as the value to the
Location header is only a fully qualified path instead of
a fully qualified URL (e.g., it doesn't begin with
http://), the server should directly return the file
rather than redirect the browser. Web Server/400 always
redirects the browser. If a fully qualified path is the
Location value, Web Server/400 redirects the browser to
that file on the current Web server.
2.9.5.4 NPH Scripts
NPH stands for "No Parse Header." If a script is requested
whose name begins with "NPH_", then the Web server will not
parse any of the response headers that the script sends
back. Typically, the Web server reads in the response
headers and transforms any headers that it recognizes into
its own response headers. This is a way to turn off this
processing. This puts the responsibility on the script to
get the response headers correct. It is not recommended to
do these types of scripts unless you have a strong
understanding of the HTTP protocol.
NOTE: Web Server/400 deviates in two ways from the CGI
standard with regard to NPH scripts.
1.With Web Server/400, an NPH script must always begin
with a response header even though the CGI standard
does not specify this. See the discussion on
conversions (Data Conversions on page 113) to
understand why.
2.In the CGI standard, scripts that begin with "NPH"
followed by a dash ("-") are considered No Parse Header
scripts, but since the AS/400 does not allow program
names to have dashes in them, the underscore ("_") is
used instead.
2.9.5.5 Data Conversions
The AS/400's native coded character set is EBCDIC. The HTTP
specifications dictate that the protocol communications that
Page 113
Commerce Server/400 2.0 Using Commerce Server/400
occur between a server and a client need to be in US-ASCII
(ANSI X3.4-1986). Additionally, the practical standard for
the textual information that is viewed on browsers is Latin
I ASCII. Both of these character sets are supported by the
AS/400, but most data generated on an AS/400 is in EBCDIC.
However, Web Server/400 takes care of automatically
converting a script's response headers and, if appropriate,
object body. In the case that a normal (non-NPH) script is
running, Web Server/400 accepts all the response headers in
the EBCDIC CCSID of the server's job. These are then parsed
and converted to US-ASCII before sending them to the
browser.
The object body is also converted if the Content-type is
explicitly set in the script's response header and the
Content-type begins with TEXT/. If Web Server/400 does
convert the object body, it is converted to the configured
Content CCSID (section 4.13.2 on page 311). In all other
cases, the script is responsible for sending the object body
in the correct format.
In the case of NPH (No Parse Header) scripts, the headers
are still read in the EBCDIC CCSID of the server's job and
converted to US-ASCII before sending them to the browser,
but they are not parsed. Other than converting them to US-
ASCII, nothing is done to them. This however, requires that
even an NPH script needs to have a response header that
matches the response header format (Response Header Format
on page 111). The Content-type response header is still
examined to determine if Web Server/400 should convert the
object body. A Content-type that begins TEXT/ causes Web
Server/400 to convert the response headers to US-ASCII and
the object body to the configured Content CCSID.
2.9.6 Status Codes
Status codes as specified in the HTTP 1.0 specification.
(http://www.w3.org/hypertext/WWW/Protocols/Overview.html)
2xx Success
The requested action was successfully received and
understood
. 200 OK
. 201 Created
. 202 Accepted
. 203 Provisional Information
. 204 No Response
. 205 Deleted
. 206 Modified
Page 114
Commerce Server/400 2.0 Using Commerce Server/400
3xx Redirection
Further action must be taken in order to complete the
request
. 301 Moved Permanently
. 302 Moved Temporarily
. 303 Method
. 304 Not Modified
4xx Client Error
The request contains bad syntax or is inherently
impossible to fulfill
. 400 Bad Request
. 401 Unauthorized
. 402 Payment Required
. 403 Forbidden
. 404 Not Found
. 405 Method Not Allowed
. 406 None Acceptable
. 407 Proxy Authentication Required
. 408 Request Timeout
5xx Server Error
The server could not fulfill the request
. 500 Internal Server Error
. 501 Not Implemented
. 502 Bad Gateway
. 503 Service Unavailable
. 504 Gateway Timeout
2.9.7 Script APIs
2.9.7.1 Script API Introduction
APIs are provided which allow developers to build scripts.
API interfaces are provided for four different programming
environments:
. ILE C
. ILE general (e.g., ILE RPG, ILE COBOL)
. OPM (e.g., RPG, COBOL, CL)
. Rexx/400
OPM and Rexx/400 interfaces are provided by programs in
library WWWSERVER.
The WWWAPI service program in library WWWSERVER provides the
ILE entry points. A bind directory named BNDDIR in library
WWWSERVER is provided to aid in developing ILE applications.
Includes are provided to aid in developing scripts in the
following programming environments:
Page 115
Commerce Server/400 2.0 Using Commerce Server/400
ILE C
Macros are provided for ILE C applications to help in
migrating C scripts from other environments to the
AS/400. See the member WWWAPI
(/qsys/wwwserver/h/WWWAPI.txt) in source file H (i.e.,
WWWAPI.H) in library WWWSERVER for more information on
ILE C interfaces.
ILE RPG
Constants that define ILE API entry points for ILE RPG
applications are available in member DWWWAPI
(/qsys/wwwserver/qrpglesrc/DWWWAPI.txt) in
WWWSERVER/QRPGLESRC.
ILE COBOL
Data items that define ILE API entry points for ILE COBOL
applications are available in member WWWAPI
(/qsys/wwwserver/qcbllesrc/WWWAPI.txt) in
WWWSERVER/QCBLLESRC.
COBOL
Data items that define API entry points for COBOL
applications are available in member WWWAPI
(/qsys/wwwserver/qcblsrc/WWWAPI.txt) in
WWWSERVER/QCBLSRC.
2.9.7.2 Script APIs
The following documents each of the script APIs that are
available. Under each API there are three interface
descriptions:
1.The first describes the ILE C interface.
2.The second describes the general ILE and OPM interface.
The ILE entry point is listed first followed by the OPM
program name in parenthesis.
3.The third describes the Rexx/400 interface. All Web
Server/400 APIs are accessed through the WWWRexx
Rexx/400 function. The first parameter is a string that
indicates which API to perform.
Each API requires all of the parameters that are listed. For
APIs that return binary values that indicate success or
failure, a negative number always indicates an error
occurred. Note that in the documentation Bytes Provided is
sometimes abbreviated to BP and Bytes Available to BA to
improve readability.
The following is a directory of the available APIs:
Get Form Variable (Get Form Variable on page 117)
Get Form Variable Enum (Get Form Variable Enum on page
119)
Read (Read on page 121)
Page 116
Commerce Server/400 2.0 Using Commerce Server/400
Write, Write with Carriage Return and Line Feed, Write
Header (Write on page 122)
Get Environment Variable (Get Environment Variable on
page 124)
UnEscape Read Data (UnEscape Read Data on page 126)
Escape Data (Escape Data on page 128)
Printf (Printf on page 130)
Get Form Variable
Get form variable is used to retrieve a form variable
(section 2.9.4 on page 107) that was passed to the script
from the browser. Get form variable is independent of the
method used to send the form data to the script. The value
returned is unescaped.
The Get Form Variable Enum (Get Form Variable Enum on page
119) function can be used to retrieve form variables that
have or can have multiple values.
WwwGetFormVarc
Prototype:
char *WwwGetFormVarc(char *pszFormVar);
where,
pszFormVar is the null-terminated name of the form
variable to retrieve. The name is dependent on the form
being processed.
Return Value: Pointer to the null-terminated form
variable's value. Do not attempt to free the returned
pointer.
Return values:
NULL : pszFormVar is NULL
other : Form variable value; empty string is returned if
value not found or set
WwwGetFormVar (WWWGETFV)
Parameters:
Form Variable Input Char(*)
Form Variable Length Input Binary(4)
Variable Value Output Char(*)
Variable Value Bytes Provided Input Binary(4)
Variable Value Bytes Available Output Binary(4)
where,
Page 117
Commerce Server/400 2.0 Using Commerce Server/400
Form Variable is the name of the form variable to
retrieve. The name is dependent on the form being
processed.
Form Variable Length is the length of the form variable
name.
Variable Value is the returned form variable value.
Variable Value Bytes Provided is the number of bytes
provided for the form variable value.
Variable Value Bytes Available is the length of the form
variable value.
Bytes available return values:
0 > BA <= BP : Complete form variable value returned
BA > BP : Partial form variable value returned
0 : Form variable value not found or set
-1 : Form variable length parameter is less
than
or equal to zero or greater than 1024
-2 : Variable value BP is less than or equal to
zero
-98 : Required parameter was omitted
-99 : Internal error occurred (e.g., memory
could not
be allocated)
Rexx/400
Prototype:
Value = WWWRexx("GETFORMVAR", FormVariableName)
where,
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
"GETFORMVAR" is the verb that performs the Get Form
Variable API. This is a static string.
FormVariableName is the name of the HTML form variable to
retrieve. The name is dependent on the form being
processed.
Return Value: A string containing the value of the HTML
form variable.
Page 118
Commerce Server/400 2.0 Using Commerce Server/400
Get Form Variable Enum
Get form variable enum is used to retrieve a form variable
value (section 2.9.4 on page 107) that was passed to the
script from the browser. Get form variable enum is needed to
retrieve a form variable's value when the form variable has
multiple values (e.g., multiple selection lists). A program
must loop, changing the value retrieving, to retrieve all of
the form variable's values.
Get form variable enum is independent of the method used to
send the form data to the script. The value returned is
unescaped.
WwwGetFormVarEnumc
Prototype:
char *WwwGetFormVarEnumc(char *pszFormVar,
long lNumber);
where,
pszFormVar is the null-terminated name of the form
variable to retrieve. The name is dependent on the form
being processed.
lNumber identifies the form variable value to retrieve.
The first value has a number of 1, the second value has a
number of 2, and so on for the rest of the values. All of
the values have been retrieved when the next number does
not return a value.
Return Value: Pointer to the null-terminated form
variable's value. Do not attempt to free the returned
pointer.
Return values:
NULL : pszFormVar is NULL
other : Form variable value; empty string is returned if
value not found or set
WwwGetFormVarEnum (WWWGETFE)
Parameters:
Form Variable Input Char(*)
Form Variable Length Input Binary(4)
Number Input Binary(4)
Variable Value Output Char(*)
Variable Value Bytes Provided Input Binary(4)
Variable Value Bytes Available Output Binary(4)
where,
Page 119
Commerce Server/400 2.0 Using Commerce Server/400
Form Variable is the name of the form variable to
retrieve. The name is dependent on the form being
processed.
Form Variable Length is the length of the form variable
name.
Number identifies the form variable value to retrieve.
The first value has a number of 1, the second value has a
number of 2, and so on for the rest of the values. All of
the values have been retrieved when the next number does
not return a value.
Variable Value is the returned form variable value.
Variable Value Bytes Provided is the number of bytes
provided for the form variable value.
Variable Value Bytes Available is the length of the form
variable value.
Bytes available return values:
0 > BA <= BP : Complete form variable value returned
BA > BP : Partial form variable value returned
0 : Form variable value not found or set
-1 : Form variable length parameter is less
than
or equal to zero or greater than 1024
-2 : Variable value BP is less than or equal to
zero
-4 : Number is less than or equal to zero
-98 : Required parameter was omitted
-99 : Internal error occurred (e.g., memory
could not
be allocated)
Rexx/400
Prototype:
Value = WWWRexx("GETFORMVAR", FormVariableName, Number)
where,
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
"GETFORMVAR" is the verb that performs the Get Form
Variable API. This is a static string.
Page 120
Commerce Server/400 2.0 Using Commerce Server/400
FormVariableName is the name of the HTML form variable to
retrieve. The name is dependent on the form being
processed.
Number identifies the form variable value to retrieve.
The first value has a number of 1, the second value has a
number of 2, and so on for the rest of the values. All of
the values have been retrieved when the next number does
not return a value.
Return Value: A string containing the value of the HTML
form variable.
Read
Read is used to read script data from standard input
(section 2.9.4 on page 107). The data is sent by a browser
using a POST or PUT method.
WwwReadc
Prototype:
long WwwReadc(void *pBuffer,
long lBufferSize);
where,
pBuffer is the return buffer.
lBufferSize is the size in bytes of the return buffer.
Return Value: Number of bytes returned in the buffer.
Return values:
>0 : Number of bytes read into the buffer
0 : No data to read
-1 : Buffer size is less than or equal to zero
-98 : Required parameter was omitted
WwwRead (WWWREAD)
Parameters:
Return Buffer Output Char(*)
Return Buffer Size Input Binary(4)
Bytes Read Output Binary(4)
where,
Return Buffer is the buffer in which to return the data
read.
Page 121
Commerce Server/400 2.0 Using Commerce Server/400
Return Buffer Size is the size in bytes of the return
buffer.
Bytes Read is the number of bytes returned in the buffer.
Bytes read return values:
>0 : Number of bytes read into the buffer
0 : No data to read
-1 : Return buffer size is less than or equal to zero
-98 : Required parameter was omitted
Rexx/400
Prototype:
Buffer = WWWRexx("READ", MaxBytesToRead)
where,
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
"READ" is the verb that performs the Read API. This is a
static string.
MaxBytesToRead is maximum number of bytes to read.
Return Value: A string containing what was read.
Write
Write is used to send script data back to the browser
(section 2.9.5 on page 110). The write functions suffixed
with CrLf add a carriage return (i.e., CR) and line feed
(i.e., LF) after the data being sent. This is used to format
the data so it is not all on one line. The write functions
suffixed with Header add 2 CR,LF pairs after the data being
sent. These functions can be used to send the document
header, which requires a blank line between the header and
the data that follows. Note that data being returned from
the script is not sent to the browser until the script ends.
WwwWritec
WwwWriteCrLfc
WwwWriteHeaderc
Prototype:
Page 122
Commerce Server/400 2.0 Using Commerce Server/400
long WwwWritec(void *pBuffer,
long lBytesToWrite);
long WwwWriteCrLfc(void *pBuffer,
long lBytesToWrite);
long WwwWriteHeaderc(void *pBuffer,
long lBytesToWrite);
where,
pBuffer is the buffer containing the data to write.
lBytesToWrite is the number of bytes to write.
Return Value: Number of bytes written.
Return values:
>0 : Number of bytes written
0 : No data written
-1 : Bytes to write is less than zero
-98 : Required parameter was omitted
WwwWrite (WWWWRITE)
WwwWriteCrLf (WWWWRTCL)
WwwWriteHeader (WWWWRTHD)
Parameters:
Input Buffer Input Char(*)
Bytes To Write Input Binary(4)
Bytes Written Output Binary(4)
where,
Input Buffer contains the data to write.
Bytes To Write is the number of bytes to write.
Bytes Written is the number of bytes written.
Bytes written return values:
>0 : Number of bytes written
0 : No data written
-1 : Bytes to write is less than zero
-98 : Required parameter was omitted
Rexx/400
Note that a normal Rexx/400 SAY will send its output over
standard output and can be used in place of the WRITE API in
Rexx/400. Important: The OS/400 PTF SF26297 must be applied
to V3R1 systems for the SAY to work. If this PTF is not
Page 123
Commerce Server/400 2.0 Using Commerce Server/400
applied and a SAY with no parameters is included in your
Rexx/400 procedure, the procedure will cause an exception.
Function Prototype:
BytesWritten = WWWRexx("WRITE", DataExpression)
BytesWritten = WWWRexx("WRITECRLF", DataExpression)
BytesWritten = WWWRexx("WRITEHEADER", DataExpression)
Procedure Prototype:
CALL WWWRexx "WRITE", DataExpression
CALL WWWRexx "WRITECRLF", DataExpression
CALL WWWRexx "WRITEHEADER", DataExpression
where,
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
"WRITE", "WRITECRLF", and "WRITEHEADER" are the verbs
that perform the Write API. These are static strings.
DataExpression is the expression to write.
Return Value: The number of bytes written.
Get Environment Variable
Get environment variable is used to retrieve a script
environment variable (section 2.9.3 on page 104) value.
WwwGetEnvc
Prototype:
char *WwwGetEnvc(char *pszEnvVar);
where,
pszEnvVar is the null-terminated name (section 2.9.3 on
page 104) of the environment variable to retrieve.
Return Value: Pointer to the null-terminated environment
variable's value. Do not attempt to free the returned
pointer.
Return values:
NULL : pszEnvVar is NULL
other : Environment variable value; empty string is
returned
if value not found or set
Page 124
Commerce Server/400 2.0 Using Commerce Server/400
WwwGetEnv (WWWGETEN)
Parameters:
Environment Variable Input Char(*)
Environment Variable Length Input Binary(4)
Variable Value Output Char(*)
Variable Value Bytes Provided Input Binary(4)
Variable Value Bytes Available Output Binary(4)
where,
Environment Variable is the name (section 2.9.3 on page
104) of the environment variable to retrieve.
Environment Variable Length is the length of the
environment variable name.
Variable Value is the returned environment variable
value.
Variable Value Bytes Provided is the number of bytes
provided for the environment variable value.
Variable Value Bytes Available is the length of the
environment variable value.
Bytes available return values:
0 > BA <= BP : Complete environment variable value
returned
BA > BP : Partial environment variable value
returned
0 : Environment variable value not found or
set
-1 : Environment variable length parameter is
less
than or equal to zero or greater than 1024
-2 : Variable value BP is less than or equal to
zero
-98 : Required parameter was omitted
-99 : Internal error occurred (e.g., memory
could not
be allocated)
Rexx/400
Prototype:
Value = WWWRexx("GETENV", EnvironmentVariableName)
where,
Page 125
Commerce Server/400 2.0 Using Commerce Server/400
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
"GETENV" is the verb that performs the Get Environment
Variable API. This is a static string.
EnvironmentVariableName is the name of the environment
variable to retrieve.
Return Value: A string containing the value of the
environment variable.
UnEscape Read Data
Unescape read data is used to unescape data received from
browser. This will convert the URL escape sequences to
EBCDIC characters (e.g., %41 goes to an EBCDIC "A" and a "+"
goes to a space).
WwwUnEscapec
Prototype:
long WwwUnEscapec(char *pszEscaped,
char *pszUnEscaped);
where,
pszEscaped is the null-terminated buffer containing the
data to unescape.
pszUnEscaped is the null-terminated buffer in which to
return the unescaped data. If the pointer is NULL the
unescaped data is returned in the escaped buffer (i.e.,
unescaped in place).
Return Value: Number of unescaped bytes in the return
buffer.
Return values:
>=0 : Number of unescaped bytes
-98 : Required parameter was omitted
WwwUnEscape (WWWUNESC)
Parameters:
Page 126
Commerce Server/400 2.0 Using Commerce Server/400
Unescape In Place Input Char(1)
Escaped Buffer I/O Char(*)
Escaped Length Input Binary(4)
Unescaped Buffer Output Char(*)
Unescaped Bytes Provided Input Binary(4)
Unescaped Bytes Available Output Binary(4)
where,
Unescape In Place indicates which buffer to return the
unescaped data in. A value of '1' returns the data in the
escaped buffer. A value of '0' returns the data in the
unescaped buffer.
Escaped Buffer contains the data to unescape.
Escaped Length is the number of bytes to unescape.
Unescaped Buffer is the buffer in which to return the
unescaped data. Not used if unescape in place is set to
'1'.
Unescaped Bytes Provided is the number of bytes provided
for the unescaped data. Must be greater than or equal to
the escaped length. Not used if unescape in place is set
to '1'.
Unescaped Bytes Available is the number of unescaped
bytes in the return buffer.
Bytes available return values:
>=0 : Number of unescaped bytes
-1 : Escaped length parameter is less than or equal to
zero
-2 : Unescaped BP is less than escaped length
-3 : Unescape in place parameter is invalid
-98 : Required parameter was omitted
-99 : Internal error occurred (e.g., memory could not be
allocated)
Rexx/400
Prototype:
Unescaped = WWWRexx("UNESCAPE", EscapedData)
where,
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
"UNESCAPE" is the verb that performs the Unescape Read
Data API. This is a static string.
Page 127
Commerce Server/400 2.0 Using Commerce Server/400
EscapedData is the value to unescape.
Return Value: A string containing the unescaped data.
Escape Data
Escape is used to escape data before sending to the browser.
Characters not in the safe URL character set are URL
escaped. EBCDIC characters are escaped to the hexadecimal
representation of their ASCII code point and spaces are
changed to pluses ("+").
WwwEscapec
Prototype:
long WwwEscapec(char *pszUnEscaped,
char *pszEscaped,
long lEscapedBytesProvided);
where,
pszUnEscaped is the null-terminated buffer containing the
data to escape.
pszEscaped is the null-terminated buffer in which to
return the escaped data. If the pointer is NULL the
escaped data is returned in the unescaped buffer (i.e.,
escaped in place).
lEscapedBytesProvided is the number of bytes provided for
the escaped data.
Return Value: Number of escaped bytes available.
Return values:
0 >= BA <= BP : All escaped data returned
BA > BP : Partial escaped data returned
-2 : Escaped BP is less than or equal to the
unescaped length
-98 : Required parameter was omitted
WwwEscape (WWWESC)
Parameters:
Page 128
Commerce Server/400 2.0 Using Commerce Server/400
Escape In Place Input Char(1)
Unescaped Buffer I/O Char(*)
Unescaped Length Input Binary(4)
Escaped Buffer Output Char(*)
Escaped Bytes Provided Input Binary(4)
Escaped Bytes Available Output Binary(4)
where,
Escape In Place indicates which buffer to return the
escaped data in. A value of '1' returns the data in the
unescaped buffer. A value of '0' returns the data in the
escaped buffer.
Unescaped Buffer contains the data to escape.
Unescaped Length is the number of bytes to escape.
Escaped Buffer is the buffer in which to return the
escaped data. Not used if escape in place is set to '1'.
Escaped Bytes Provided is the number of bytes provided
for the escaped data. Must be greater than or equal to
the unescaped length. Not used if escape in place is set
to '1'.
Escaped Bytes Available is the number of escaped bytes
available.
Bytes available return values:
0 >= BA <= BP : All escaped data returned
BA > BP : Partial escaped data returned
-1 : Unescaped length parameter is less than
or
equal to zero
-2 : Escaped BP is less than unescaped length
-3 : Escape in place parameter is invalid
-98 : Required parameter was omitted
-99 : Internal error occurred (e.g., memory
could
not be allocated)
Rexx/400
Prototype:
EscapedData = WWWRexx("ESCAPE", UnescapedData)
where,
WWWRexx is the Rexx/400 function that handles all Web
Server/400 API calls.
Page 129
Commerce Server/400 2.0 Using Commerce Server/400
"ESCAPE" is the verb that performs the Escape Data API.
This is a static string.
UnescapedData is the value to escape.
Return Value: A string containing the escaped data.
Printf
Printf is used to return formatted script data to the
browser. Printf is only available to ILE C applications. The
parameters are the same as the C printf function. Note that
data being returned from the script is not sent to the
browser until the script ends.
WwwPrintfc
Prototype:
long WwwPrintfc(char *pszFormat,...);
where,
pszFormat is the null-terminated formatting string. This
string, when expanded, cannot exceed 8K in length.
... are the variables required by the format string.
Return Value: Number of bytes sent to the browser.
Return values:
>=0 : Number of bytes sent to the browser
-98 : Required parameter was omitted
2.9.8 Creating Script Programs
2.9.8.1 Supported Languages
Script programs can be any program that can be called by
another AS/400 program or a file object that contains
REXX/400 procedure code. The only limitation is that in
order for that language to receive input and return output,
the language needs to be able to call, with parameters, one
of the following types of Application Program Interfaces:
1.Original Program Model (OPM) APIs (e.g., RPG, COBOL,
CL)
2.Integrated Language Environment (ILE) APIs (e.g., ILE
C, ILE RPG, ILE COBOL)
3.ILE C
4.REXX/400 Procedure or Function
Page 130
Commerce Server/400 2.0 Using Commerce Server/400
2.9.8.2 Making a Script Available to Web Server/400
There are three factors that make a script program available
to a browser:
. Enable Scripts (section 4.12.1 on page 308)
Configuration Value
This value must be set to InsideScriptLib or
OutsideSriptLib in order for scripts to be run at all.
. Script Library (section 4.12.2 on page 309)
Configuration Value
If Enable Scripts is set to InsideScriptLib, the script
program must be placed in a library that is included in
the Script Library configuration value. Actually, the
only objects stored in a Script Library that can be
accessed through the Web server are programs.
Note: REXX/400 procedures can only be called from
within a library specified by the Script Library
configuration value. Files containing REXX/400 code
outside of a Script Library will always be served as
text files.
. Program Object Authority
The Server User Profile (section 4.13.17 on page 324)
must have at least Execute data authority and
Operational object authority to the program object to
allow the Web server to call the script. The Server
User Profile must have at least this much authority to
the library that contains the script. Typically, the
Server User Profile would have *USE authority to both
the library and the script.
2.9.8.3 How Do Browsers Access Scripts?
There are two common ways for providing users access to a
script. One is to create an HTML form that has a submit
button that calls a script. The other is to have a hyperlink
that directly calls a script.
HTML Form
An HTML form creates a user interface on the browser for
collecting data from the user. When this data is
submitted by the user, a script is called that can access
everything the user typed in. The HTML form is simply
some special markup in an otherwise normal HTML document.
A form provides entry fields, check boxes, radio buttons,
and lists. Below is a simple form that demonstrates the
basics of how to use the form to collect data for a
script.
Page 131
Commerce Server/400 2.0 Using Commerce Server/400
The user would request the above document, fill in a
value (for instance, "Text1" and "Text2") in the entry
field, and then press the submit button. This would
request the formscript script using the POST method. The
standard input to the script would be:
Var1Name=Text12Name=Text2
Hyperlink
If a script doesn't require dynamic user input, a simple
hyperlink to the script would work fine. This would be
done by including a normal anchor tag (...) in an HTML document. Each URL used in
the hyperlink to the script can have different extra path
information (PATH_INFO on page 105) or query strings. For
example, the following two hyperlinks would call the
script weather using the GET method. The first would
request the weather for Kalamazoo, Michigan and the
second would request the weather for Rochester,
Minnesota.
Kalamazoo, Michigan
Rochester, Minnesota
2.9.8.4 Accessing AS/400 Objects within Scripts
If a script accesses AS/400 objects (e.g., database files)
and the language (e.g., RPG/400) being used does not support
qualifying the object with a library, two methods can be
used to locate the object:
1.The object can be found using the library list. The
script's library list is the library list of the user
that started the server.
2.A CL program can be used to override to the desired
object. The CL program would then call the script code.
2.9.8.5 Running Scripts from the Command Line
Script programs are just normal programs so they can, of
course, be called from the command line. However, script
programs generally will not work when called outside of Web
Server/400 since the browser input is not available to the
script. The Web Server/400 APIs will just return a blank
string or indicate that zero bytes are being returned.
Page 132
Commerce Server/400 2.0 Using Commerce Server/400
2.9.8.6 Debugging Scripts
Not everyone can write a script program exactly right the
first time. Sometimes the script will produce the wrong
results or even end abnormally. The first type of problem,
faulty results, can be debugged through traditional methods
with some minor twists:
1.Use the browser as your window to the program. Send
input values or calculated values back to the browser
in the body of the result.
2.View the exact source of the HTML being interpreted by
your browser instead of the formatted version. Most
browsers have a menu item that allows you to "View the
Source".
3.Try different browsers to make sure the problem isn't a
browser problem. Also, make sure your script works well
with all browsers rather than just your favorite.
If a "Bad Request" error is displayed on your browser
instead of the output you expected your script to create,
then most likely the script caused an exception during
execution or the Server User Profile did not have proper
authority to the program object or file. The first place to
check is your Error Log (section 2.16.6 on page 176). This
will indicate whether it is an authority problem or whether
the program ended abnormally.
1.If it is an authority problem change the program
object's or file object's authority.
2.If the program ended abnormally, check the job log of
the request processor that handled your script request.
This can be done using the WRKACTJOB command specifying
option 5 on the proper job and then selecting menu item
10. Note: To keep the job log from becoming very large,
the job log is cleared after every ten (10) requests.
If your job log entry is not there this was probably
the tenth request so request the script again.
Page 133
Commerce Server/400 2.0 Using Commerce Server/400
2.10 Accessing Spooled Files
2.10.1 Spooled File Support
The server supports returning formatted data from spooled
files. By default the server maintains the spooled file's
line spacing, bold attributes, and underline attributes.
Spooled files can also be copied into and returned formatted
from database files (SPLF on page 96).
2.10.2 Specifying a URL
The server supports three general formats of URLs (section
2.3 on page 53) that access spooled files (section 2.3.9 on
page 61):
http://server: / port splf/jobname/user/jobnbr/splfname
or
http://server:port/splf/jobname/user/splfname
or
http://server:port/splf/jobname/jobnbr/splfname
where,
server
is the fully qualified domain name of the machine that
contains the resource.
port
is the socket port on the host machine that is running
the HTTP server. The :port is optional. If it is not
included, it defaults to port 80.
splf
indicates that the data is contained in a spooled file on
the AS/400.
jobname
the name of the job that created the spooled file.
user
the user name that identifies the job's user profile. If
the user is not supplied then the job number must be
passed. If the user is not passed then the URL may not
uniquely identify the spooled file which will result in
an error being returned. The WRKJOB JOB(jobname) command
Page 134
Commerce Server/400 2.0 Using Commerce Server/400
can be used to identify all the jobs in the system with
the specified jobname.
jobnbr
identifies the job's job number. If the job number is not
supplied then the user must be passed. If the job number
is not passed then the URL may not uniquely identify the
spooled file which will result in an error being
returned. The WRKJOB JOB(jobname) command can be used to
identify all the jobs in the system with the specified
jobname.
splfname
specifies the name of the spooled file. By default the
job's last spooled file with the specified name is
returned. The SPLNBR (SPLNBR on page 136) keyword
parameter can be used to retrieve a specific spooled
file.
2.10.3 Determining Content Type
The content type (section 2.13 on page 143) indicates the
type of data that is being returned from the server to the
browser. Spooled files will normally contain plain text.
The following order is used to determine the content type of
data stored in a spooled file:
. URL contains a valid content type extension (Content
Type extensions can be included on page 59)
. Defaults to plain text content type
2.10.4 Authority
The server user profile (section 4.13.17 on page 324) must
meet one or more of the following conditions to access the
spooled file:
. Owner of the spooled file
. *READ authority to the queue on which the spooled file
resides and the queue is specified as DSPDTA(*YES)
. *SPLCTL authority
. *JOBCTL authority and the queue on which the spooled
file resides is specified as OPRCTL(*YES) and
DSPDTA(*YES or *NO)
. Owner of the queue on which the spooled file resides
and the queue is specified as AUTCHK(*OWNER) and
DSPDTA(*YES or *NO)
. Read, add and delete authorities to the queue on which
the spooled file resides and the queue is specified as
AUTCHK(*DTAAUT) and DSPDTA(*YES or *NO)
Page 135
Commerce Server/400 2.0 Using Commerce Server/400
2.10.5 Supported Keywords
The following keyword parameters (section 2.8.2 on page 84)
are supported when processing spooled files:
SPLNBR(number | *LAST | *ONLY)
The spool number is used to identify a specific spooled
file. Valid values are:
. number - The number of the spooled file.
. *LAST - The spooled file identified by the URL with
the highest number is returned.
. *ONLY - The job only has one spooled file with the
passed spooled file name.
If the SPLNBR keyword is not supplied then the server
defaults to SPLNBR(*LAST).
Samples:
. SPLNBR(*LAST)
. SPLNBR(*ONLY)
. SPLNBR(2)
SPLF(0 | 1)
Used to specify output formatting for the spooled file.
Valid values are:
. '0' - Output the spooled file as pre-formatted data.
This option uses a fixed font which maintains
columns.
. '1' - Output the spooled file as formatted data.
This option uses a variable font and should only be
used when the spooled file does not contain columns.
If the line spacing is not correct it is because the
browser being used does not support multiple line
breaks.
If the URL indicates the spooled file contains HTML data
then either option can be specified and the data is
returned as is from the spooled file. Non-text content
types will return the spooled file data with the printer
control characters.
If the SPLF keyword is not supplied then the server
defaults to SPLF(0).
Samples:
. SPLF(0)
. SPLF(1)
HEADER(library/src-pf member[.html])
Used to specify a header document to include before the
spooled file data. A header can be used to set the
Page 136
Commerce Server/400 2.0 Using Commerce Server/400
document title and describe the spooled file data that
follows.
The first part of the header keyword value indicates the
library and source physical file that contains the member
containing the header information. The slash separating
the library and src-pf should be escaped (e.g., / = %2F).
The library specified must be accessible through the
configured include libraries (section 4.9.1 on page 292).
The second part specifies which member contains the
header data. The data contained in the member is assumed
to be plain text unless one of the following two methods
is used to indicate the member contains HTML data:
1. .HTML is appended to the member name
2. Member type is set to HTML
Samples:
. HEADER(LIBRARY/SRCFILE+HEADERMBR)
. HEADER(LIBRARY%2FSRCFILE+HEADER.HTML)
FOOTER(library/src-pf member[.html])
Used to specify a footer document to include after the
spooled file data. A footer can be used to display
summation information.
The first part of the footer keyword value indicates the
library and source physical file that contains the member
containing the footer information. The slash separating
the library and src-pf should be escaped (e.g., / = %2F).
The library specified must be accessible through the
configured include libraries (section 4.9.1 on page 292).
The second part specifies which member contains the
footer data. The data contained in the member is assumed
to be plain text unless one of the following two methods
is used to indicate the member contains HTML data:
1. .HTML is appended to the member name
2. Member type is set to HTML
The footer should not include either the or
tag.
Samples:
. FOOTER(LIBRARY/SRCFILE+FOOTERMBR)
. FOOTER(LIBRARY%2FSRCFILE+FOOTER.HTML)
PAGES(start-end)
Used to specify which spooled file pages are to be
returned.
The format of the PAGES keyword value is the starting
page number followed by a hyphen and then the ending page
number. If the starting page number is greater then the
total number of spooled file pages then no spooled file
data is returned. The ending page number may be set to
Page 137
Commerce Server/400 2.0 Using Commerce Server/400
the special value *LAST. The starting and ending page
values are inclusive.
If PAGES is not specified then all of the pages will be
returned.
Samples:
. PAGES(1-*LAST)
. PAGES(10-*LAST)
. PAGES(5-8)
SENDLEN(0 | 1)
Used to specify if the content length should be sent.
Using the SENDLEN keyword overrides the send file content
length configuration value (section 4.13.10 on page 319).
Valid values are:
. '0' - Do not send content length
. '1' - Send content length
Samples:
. SENDLEN(0)
. SENDLEN(1)
2.10.6 Output Considerations
Document Title
The title of the document (i.e., spool file) returned is
set to the second-level message text of message ID
(WWW0913 - formatted spool file output, or WWW0914 -
preformatted spool file output) in the WWWMSGF message
file. If a different default title is desired then change
the second-level message text. If the spool file contains
HTML data then the spool file should set the document
title.
2.10.7 Restrictions
Graphic, binary, and bar code data contained in a spooled
file is not returned by the server. If data is defined using
the DFNCHR or TRNSPY keywords the data is replaced with
blanks.
2.10.8 Examples
The following are examples of URLs that access spooled
files:
http://system/splf/dsp01/user/123456/splf
The URL fully identifies a spooled file named SPLF.
Page 138
Commerce Server/400 2.0 Using Commerce Server/400
http://system/splf/dsp01/user/splf
The job number is not needed to identify the spooled
file.
http://system/splf/dsp01/123456/splf
The user is not needed to identify the spooled file.
http://system/splf/dsp01/user/123456/splf?SPLNBR(3)
The URL fully identifies a spooled file. The spooled file
SPLF with a number of 3 is returned.
http://system/splf/prtdoc/user/123456/office?SPLF(1)
The URL fully identifies a spooled file named OFFICE. The
OFFICE spooled file contains a letter which is returned
with a variable font.
http://system/splf/prtdoc/user/123456/report.html
The URL fully identifies a spooled file named REPORT. The
REPORT spooled file contains HTML data.
Page 139
Commerce Server/400 2.0 Using Commerce Server/400
2.11 Ultimedia System Facilities
Web Server/400 supports Ultimedia System Facilities (USF),
enabling the user to access multimedia objects stored within
the USF multimedia repository.
USF is a client/server application which allows the user to
capture multimedia objects and store them in a repository on
the AS/400. This gives the web author a platform on which to
create multimedia objects (video, audio, images, text files
...), manage the location of these objects and documents in
one convenient location on the AS/400. Each USF multimedia
object is given an object ID which can be used to uniquely
identify that object. This 20 character object ID would then
be passed within the USF URL (section 2.3.8 on page 60) to
identify the multimedia object.
Further information can be found in the following areas.
. USF URL example and rules (section 2.3.8 on page 60).
. Samples (../samples/USFSamp.htm) are provided to
demonstrate Web Server/400's ability to access USF
Objects.
Note: The USF object's multimedia repository path attribute
is used to resolve the content type and location of the data
used for the request. The Web Server/400 product supports
all content types being retrieved from within the USF
repository.
Please refer to the USF publications provided with the
OS/400 operating system for further details about USF and
its multimedia repository.
Page 140
Commerce Server/400 2.0 Using Commerce Server/400
2.12 Image Mapping Feature
The image mapping feature of Web Server/400 allows a user to
map parts of an image to documents. When the user clicks on
different areas of the image with the browser, the user will
be redirected to a document appropriate to that part of the
image.
When describing the areas of the image, you can use shapes
such as circles (section 4.8.1 on page 287), polygons
(section 4.8.6 on page 290) and rectangles (section 4.8.7 on
page 291). A user can also specify points (section 4.8.5 on
page 289), with the nearest point being used to pick a
document. A default (section 4.8.2 on page 287) can be
specified, which is used when no other match is made.
2.12.1 Including a Mapped Image
To include a mapped image, include a reference like the one
below:
The example above has the following parts
qsys
An alias (section 2.4 on page 65) into *QSYS.
webcgi
A script library (see configuration issues below).
MapFile
The name of the image map mapping file (section 5.3.2 on
page 341).
picture.gif
An image the user can click on.
2.12.2 Configuration Issues
In addition to building a map file (above), you must set up
a global image map configuration file (section 5.3.1 on page
341), and set up an alias into QSYS, as well as enable
scripts correctly.
Page 141
Commerce Server/400 2.0 Using Commerce Server/400
To support the above example, an alias (section 4.3.1 on
page 261) entry that redirects QSYS into the root of *QSYS
is required. Also see more about aliases in general (section
2.4 on page 65).
Image mapping is supported as a pseudo-script (section 2.9
on page 102) that must be specified in a script library
(section 4.12.2 on page 309) entry and enable scripts
(section 4.12.1 on page 308) must be set to Yes. In the
above example, webcgi would need to be listed as a script
library.
2.12.3 Using Your Own Image Mapping
You may write your own image mapping support as a script
(section 2.9 on page 102) and reference it as above. The
image mapping support provided with Web Server/400 is
written as a pseudo-script and if the server sees a script
in the referenced library, it will be executed instead of
the shipped image mapping feature.
Page 142
Commerce Server/400 2.0 Using Commerce Server/400
2.13 Content Types
Within the HTTP protocol the content type is a header field
returned by the Web server as part of the response. This
value is used to indicate the Internet media type of the
information being returned. The content type is used by the
browser to determine what mechanism to use to display the
data returned from the Web server.
A content type is comprised of a type and subtype
represented as type/subtype. Where subtype further describes
the type parameter. For example image/bmp is an image type
with a subtype of bmp (representing bitmap). This would
indicate an image with the data stored as a bitmap.
The Web Server/400 product uses file extensions to determine
what content type is associated with a particular file. This
is configured within the content type configuration file
(section 5.2.3 on page 340).
Internet media type is a term which was originally derived
from the Multipurpose Internet Mail Extensions (MIME)types.
RFC 1521 (http://ds.internic.net/rfc/rfc1521.txt) and 1522
(http://ds.internic.net/rfc/rfc1522.txt) discuss and define
the MIME types definition.
There are two different categories of content types:
officially registered
The registration process is defined within the Request
for Comments (RFC) numbered 1590
(http://ds.internic.net/rfc/rfc1590.txt). The
registration authority is the Internet Assigned Numbers
Authority (IANA). RFC 1521
(http://ds.internic.net/rfc/rfc1521.txt) and 1522
(http://ds.internic.net/rfc/rfc1522.txt) also have
information regarding the registration of MIME types.
non-registered
The non-registered content types are content types which
have not been officially registered with the IANA. These
content types have a type which begins with the "x-"
characters. If you which to add any unregistered types to
the content type configuration file (section 5.2.3 on
page 340) they should also begin with the "x-" characters
Page 143
Commerce Server/400 2.0 Using Commerce Server/400
2.14 Dynamic Indexing
The term "directory" throughout this section refers to any
of the following:
IFS and QDLS File System
a directory containing subdirectories and files
QSYS file system
a library containing files, or a file containing members
QSYS library
the QSYS library is a special library, it is the only
library that can contain other libraries as well as
files.
2.14.1 Dynamic Indexing
The Dynamic Indexing feature of Web Server/400 provides an
index of a directory. This index is provided by a
dynamically built HTML document which includes a hyper-link
to each of the index items. The hyper-links to other
directories within the index will result in a dynamic index
of the directory chosen. This is a convenient way to
traverse through directories.
Since this index is built dynamically, any changes made
within the directory will be incorporated the next time the
index is requested. A good example of this is a view of
research papers documented using the HTML markup language
submitted through an FTP site. The directory access for
viewing the documents could be Web Server/400, while the
transfer mechanism of providing and maintaining the
documents could be an FTP or Gopher server accessing the
same directory.
2.14.2 Disabling Dynamic Indexing
There are two different methods to disable the dynamic
indexing feature. If you prefer to disable this feature
completely for all directories, configure the Index Default
View (section 4.7.2 on page 278) parameter to do so. If you
prefer to disable the dynamic indexing feature only for a
particular directory include the index name file (section
4.13.7 on page 315) within that directory. Any directories
which contain the index name file (section 4.13.7 on page
315) within a directory will display the index name file in
place of the dynamic index view.
Page 144
Commerce Server/400 2.0 Using Commerce Server/400
The use of a symbolic link for the index name file would be
an efficient way to disable the dynamic index view of a
directory. The symbolic link would allow the WebMaster to
give the main file a name which better describes the files'
purpose other than the generic name normally specified for
the index name file. By using a symbolic link when you
change the main file the symbolic link will automatically
reflect the changes without having to perform dual
maintenance on the files. The same file will be resolved
regardless of whether the URL contains the descriptive name,
or just ending in a '/' after the directory name is
specified.
2.14.3 Features of Dynamic Indexing
2.14.3.1 Header and Footer Files
The dynamic indexing feature supports the ability to include
the contents of an HTML marked up file or the contents of a
plain text file at the head and foot of each directory.
These files will be referred to as the header (section 4.7.5
on page 281) and footer (section 4.7.4 on page 280). Neither
are required and one is allowed without the other.
If the header is resolved with the content type of
text/html, then it is assumed that the header file will
include all the appropriate HTML markup tags up to and
including the tag. It is also assumed that if there
is a text/html header that there is a footer which will
appropriately end the HTML tags started by the header. In
this case the server will not add any HTML tags other than
those necessary for the actual index list.
If the header is not resolved or is considered not to be
text/html then the server will include the following sets of
tags:
.
.
. (the title's text will specify the directory
name)
. <BODY>
If the header or footer is resolved with a content type
other than text/html the server will wrap the contents of
the file with preformatted text tags (<PRE> and </PRE>).
2.14.3.2 Excluding Files
Included with the dynamic indexing feature is the support to
exclude (section 4.7.3 on page 279) files from the index
Page 145
Commerce Server/400 2.0 Using Commerce Server/400
list. This can be accomplished through configuration. The
configuration allows the WebMaster to specify multiple file
names to be excluded from the index list that is returned to
the user. The list of file names supports the use of the '*'
and '?' wildcard characters. The list of file names is case
insensitive in all file systems (including QOpenSys which is
a case sensitive file system). By default, the default
header and footer files will be excluded from index lists.
2.14.3.3 Send Directory Content Length
Dynamic Indexing has a configuration option, Send Directory
Content Length (section 4.7.8 on page 285), which specifies
whether the content length will be sent back to the browser
for dynamic indexing requests. If the content length is not
sent back to the browser, the browser will be unable to
determine how much of the response data is left to be
received. However, especially for large directories, the
performance when the content length is not sent back will be
better than if it is requested to be returned in the
response header. The reason for this performance gain is
that since the directory index is built dynamically, the
size of the output is not known until the entire output has
been built. Since the content length is part of the response
header which is sent back prior to the index data, the
entire output will be held back until the content length is
calculated.
2.14.3.4 Enhanced and Simple Views
There are two different views available for the dynamic
index:
Simple view.
The simple view of a directory would include a sorted
list of the file names and subdirectories displayed as
hyper-links to those files or subdirectories. The view is
created using the unordered list HTML tags.
Enhanced view
The enhanced view of a directory would include a sorted
list of the file names and subdirectories displayed as
hyper-links to those files or subdirectories. The view is
created as a table like view through the use of
preformatted text HTML tags. The table will include
additional pieces of information not available in the
simple view. The WebMaster can control how much
additional information will be included.
There are a number of configurable values associated with
the views of the dynamic index. The first value allows you
to determine which view is the default view (section 4.7.2
Page 146
Commerce Server/400 2.0 Using Commerce Server/400
on page 278). The default view can be configured to be
Simple, Enhanced, or Disabled all together. The simple view
is a basic list of the index (sorted by file name). The
enhanced view includes additional information for each
entry. The amount and type of additional information
available with the enhanced view (Index Style) (section
4.7.7 on page 284) is configurable by the WebMaster.
Generally speaking, the Enhanced view of a directory index
takes longer to provide than a Simple view since more
information is gathered and sent to the browser.
Both the simple and enhanced views have the option to
include a statement with a hyper-link at the top of each
index allowing the user to choose to see the other view. For
example, at the top of a directory's simple view, the
statement referring to the enhanced view of this index
(including a hyper-link) would be available. If the
WebMaster did not choose to show this statement it can be
disabled through the default view (section 4.7.2 on page
278) configuration. An example of where this hyper-link
would be useful is when the WebMaster chooses the simple
view of directories as the default, (most likely to enhance
the speed of the dynamic index). If the user would like to
view the size of the files prior to requesting to view them,
the user may click on the enhanced view for the additional
information available.
The keywords included within a Dynamic Indexing URL which
override the view of a directory are always available when
Dynamic Indexing is allowed. The keywords are
?Simple
The simple view of dynamic directory.
/samples/index/?Simple
This URL would display the simple view of the
DocumentRoot (section 4.6.2 on page 271)/samples/index/
directory.
?Enhanced
The enhanced view of dynamic directory.
/samples/index/?Enhanced
This URL would display the enhanced view of the
DocumentRoot (section 4.6.2 on page 271)/samples/index/
directory.
Enhanced View Detailed Information
Including Icons
One of the additional pieces of information available in the
enhanced view is an icon. The WebMaster can configure the
enhanced view to include an icon for each index item. In
Page 147
Commerce Server/400 2.0 Using Commerce Server/400
addition to including the icon, the WebMaster can specify
whether the icon will include a hyper-link (MakeIconsLinks)
(section 4.7.7 on page 284) to the indexed item as well as
the hyper-link on the index item name.
There are six different options available for icon selection
index items, all of which are configurable.
. Parent Directory (section 4.7.6 on page 282)
. Directory (section 4.7.6 on page 282)
. Table Heading (section 4.7.6 on page 282)
. Default (section 4.7.6 on page 282)
. Specify an icon by content type (section 4.7.6 on page
282)
. Override the content type or default icon by using the
file's extension (section 4.7.6 on page 282)
Including File Descriptions
The enhanced view of the index allows the WebMaster to
configure descriptions (section 4.7.7 on page 284) to be
displayed for each file within the index. There are multiple
locations where the descriptions may be extracted from.
These locations vary depending upon the type of file in the
index, and the file system where the dynamic index is being
retrieved from.
If the WebMaster has configured the server to include HTML
TITLES (section 4.7.7 on page 284) when a file's content
type resolves to text/html, the TITLE found within the
text/html file will be searched for first. If the file's
content type does not resolve to text/html or a TITLE is not
found within the file, the Global Access configuration file
(section 5.4.1 on page 343) will be searched for a
description (section 4.7.1 on page 277) matching the file
name. The HTML TITLES and Access Control file descriptions
are available for all files residing in all file systems.
In the QSYS file system there is one additional location
where the description will be searched for if it is not
already found. When displaying the dynamic index of a
library, the OS/400 Object's text description will be used.
When displaying the dynamic index of a file within the QSYS
file system, the member's text description within the file
will be displayed.
There is a limit to the number of bytes that the Web
Server/400 product will search for a description when the
include HTML TITLES (section 4.7.7 on page 284) option has
been configured. The limit is file system dependent. Within
the ROOT and QDLS file systems the first 512 bytes must
contain the HTML keywords and in order for the TITLE to be
Page 148
Commerce Server/400 2.0 Using Commerce Server/400
used as the description. Within the QSYS file system 1024
bytes will be searched.
Note: including the HTML title (section 4.7.6 on page 282)
as the description could degrade the server's performance.
Including the HTML title as the description requires that
each file included within the dynamic index, which has a
text/html content type, to be opened, read and the file's
contents searched through for the HTML TITLE. Directories
with a large number of HTML files potentially require
significant additional processing.
Including Date and Time
The enhanced view of the dynamic index provides the ability
for the WebMaster to configure the server to query and
return the last date and time (section 4.7.7 on page 284)
the file was modified. The last modified date is available
without the time value however, the last modified time is
not available without the date information.
Including File Size
The enhanced view of the dynamic index provides the ability
for the WebMaster to configure the server to query and
return the size (section 4.7.7 on page 284) of the file.
This can be useful to the user if they want to determine how
big a file is prior to viewing it.
2.14.3.5 Samples
Shipped with the Web Server/400 product are some sample
(../samples/dynindex.htm) directories set up to demonstrate
the dynamic indexing feature.
Page 149
Commerce Server/400 2.0 Using Commerce Server/400
2.15 Protecting Your AS/400 Information
When configuring your Web Server, you should think about the
kinds of information on your AS/400 and to whom you want to
make it available. There are three basic categories, defined
by their availability:
Unavailable through the Web Server
This is information that you don't want anyone to view
through the Web Server. It may be personal or valuable
information that is on the same AS/400 as the Web Server,
but you don't want users to be able to access it through
the Web Server.
The two methods you have for protecting this information
are OS/400 authority and Web Server/400 scope control.
OS/400 authority is very strong, but may be hard to
configure and maintain. Web Server/400 scope control
should be easier to maintain and is already set up when
you install the server.
Note that a third method, access control can also be used
for this information. Access control will be further
described later.
Available to all users who have access to the Web Server
This is information that you want generally available. It
may include press releases and other announcements or
marketing material. If your Web Server is only available
through an internal network, you might include other
information here, such as company-wide announcements.
The same two methods as above are used to make
information available (OS/400 authority and Web
Server/400 scope control). The difference is that you
would use the methods to make this information available,
rather than unavailable.
Available to a subset of users who have access to the Web
Server
This is information that should be available to some
users who have access to the Web Server, but not all. It
might include information only available to customers, or
information only available internally, even though the
Web Server itself if available to the public (e.g.
through the Internet).
The method for protecting this information is access
control. Using access control, you can specify (on a per-
directory basis if you like) who can access information,
either based on the on the machine they are using or
Page 150
Commerce Server/400 2.0 Using Commerce Server/400
based on a user name and password they enter, or a
combination of the two.
Note that this document only describes protecting your
AS/400 information in regards to Web Server/400. Other
software such as Telnet and FTP pose additional concerns
which are not addressed here.
2.15.1 OS/400 Authority
This is familiar to AS/400 system administrators and is very
strong (it can be configured to meet the requirements for C2
security, as defined by the United States Department of
Defense).
For OS/400 authority to be effective, your system's security
level (system value QSECURITY) should be set to at least 30.
Web Server/400 has been developed and tested at security
level 40.
The server jobs (daemon and request processors) that serve
content run under the configured server user profile
(section 4.13.17 on page 324). The server user profile
should have the following authorities:
. *USE to any documents you want to make available to
browsers.
. *USE to any scripts (section 2.9 on page 102) the
server should be able to execute.
. *USE to the WWWSERVER/WWWDAEMON program and to the
QSYS/QSYSNOMAX job queue.
. The server user profile must be registered in the
system directory in order to access Document Library
Services (DLS) folders and documents.
To protect information from being accessed through Web
Server/400 using OS/400 authority, you must ensure that the
server user profile does not have access to it. You can do
this by either specifically excluding the server user
profile, or by excluding *PUBLIC.
2.15.2 Web Server/400 Scope Control
Web Server scope control refers to configuration values that
affect the scope of the information the server will attempt
to retrieve. Following are references to more information
related to those configuration values:
. Server root path (section 4.6.5 on page 274)
. Include library (section 4.9.1 on page 292)
. Enable Scripts (section 4.12.1 on page 308)
. Script library (section 4.12.2 on page 309)
. Public user directory (section 4.14.1 on page 328)
Page 151
Commerce Server/400 2.0 Using Commerce Server/400
2.15.3 Web Server/400 Access Control
While OS/400 authority is very strong, it is inflexible
because it is based on the user profile of the person
starting the server and on the server user profile. The
server user profile either has access to an object or not.
Access control takes into account information about the
person requesting the information, such as the workstation
they are using and the user name and password they enter.
You can find more information about access control in the
tutorial (section 2.15.6 on page 155), an access control
example (section 2.15.7 on page 159) and a detailed
description of how limit sections are evaluated (section
2.15.8 on page 161).
2.15.3.1 Modes For Evaluating Access
Access control is evaluated in one of two modes: normal mode
or administration mode (section 2.18 on page 187). Normal
access control is governed by the directory based
configuration file (section 5.4.1 on page 343).
Administrative access control is governed by the
administrative access configuration file (section 5.4.2 on
page 344).
By default, all hosts and users have normal access to all
documents (that OS/400 authority allows), and no hosts and
users have administrative access to any documents.
2.15.3.2 Ways Of Controlling Access
Web Server/400 allows access to be restricted in two ways,
which may be used separately or combined. For greatest
security, both should be used together.
Host filtering
Allows restriction of access to information based on the
IP address or domain name of the machine (host)
requesting the information.
User authentication
Allows restriction of access to information based on a
user ID and password the user enters.
Evaluating Web Server/400 access involves a two step
process:
1.Host filtering will be checked first. If host filtering
is not configured or allows access, the server goes on
to the next step. If host filtering does not allow
access, the server will forbid access.
2.User authentication is checked. If user authentication
is not configured or allows access, then access is
granted. If user authentication does not allow access,
the server will forbid access.
Page 152
Commerce Server/400 2.0 Using Commerce Server/400
Note that Web Server/400 access control is based entirely on
files and their relationship within IFS. Because Web
Server/400 does not take into account symbolic links, you
must protect any symbolic links leading to a file in the
same way you protect the file itself.
Remember, even if Web Server/400 access control allows
access, OS/400 authority must allow the server user profile
access to information before it can be sent back to a
browser.
2.15.4 Further Information About Protecting Your AS/400
The following topics are related to protecting your AS/400:
. Server user profile (section 4.13.17 on page 324)
. Access log (section 2.16.4 on page 166) (for auditing
accesses and attempted accesses)
. Domain name lookup (section 4.13.5 on page 313)
(affects host filtering)
. Authentication User Storage (section 2.15.5 on page
154)
. Access control configuration files
. Directory based configuration file path (section
4.2.13 on page 255)
. Directory based configuration file (section 5.4.1 on
page 343)
. Administrative access control file path (section
4.2.1 on page 243)
. Administrative access configuration file (section
5.4.2 on page 344)
. User access file (section 5.4.3 on page 345)
. Group access file (section 5.4.5 on page 346)
. Configuration values used in access control
configuration files
. Directory section start (section 4.2.12 on page 254)
. Authentication group file (section 4.2.4 on page
246)
. Authentication realm name (section 4.2.5 on page
247)
. Authentication type (section 4.2.7 on page 249)
. Authentication user file (section 4.2.9 on page 250)
. Limit section start (section 4.2.15 on page 257)
. Limit section end (section 4.2.14 on page 256)
. Directory section end (section 4.2.11 on page 253)
. Order (section 4.2.16 on page 258)
. Allow hosts (section 4.2.2 on page 244)
. Deny hosts (section 4.2.10 on page 251)
. require user authentication (section 4.2.17 on page
259)
Page 153
Commerce Server/400 2.0 Using Commerce Server/400
2.15.5 Authentication User Storage
You have two choices to make when you are setting up
authentication: what kind of file to store users in and the
user password storage mode.
2.15.5.1 What Kind of File to Store Users In
You can choose to store users in database files or stream
files. This choice can be made separately for each user file
(e.g. you can have one user stream file and one user
database file for the same server).
. Stream File
This file type is compatible with NCSA servers and is
ideal for holding a small number of users that does not
change very often. Because it is read into the memory
of each request processor during server startup and
reconfiguration, it is not good for files containing a
large number of users.
. Database File
This file type is ideal for large numbers of users and
for cases where the list of users changes often. This
file type is not read into memory by each request
processor, conserving system memory. There is a small
additional performance penalty to pay for each request
that is authenticated with this type of file because
the server needs to access the database file for each
request.
Remember that if performance is a concern, you can protect
one area (or set of areas) with a stream file while
protecting another area (or areas) with a database file. You
choose the type of file to store users in with the
Authentication User File (section 4.2.9 on page 250)
configuration value. To migrate stream files into database
files, you can use the MIGWWWUSR (section 3.3.28 on page
222) command.
2.15.5.2 User Password Storage Mode
The way that user passwords are stored (for authentication
only, not for Webulator/400) changed starting with Web
Server/400 version 1.3. The Web Server can be configured to
use either the new mode or the old mode (for backward
compatibility). The new mode is called Normalized while the
old mode is called Compatible.
. Normalized Password Storage
In this mode, the server converts all passwords to
upper case and to a common CCSID before hashing them
with the RSA Data Security, Inc. MD5 Message-Digest
Page 154
Commerce Server/400 2.0 Using Commerce Server/400
Algorithm. The conversion to upper case allows the
server to match passwords in a case-insensitive way,
which is in line with general AS/400 operation. The
conversion to a common CCSID allows users with
different CCSIDs to manage the same user file.
. Compatible Password Storage
In this mode, the server does no conversion before
hashing passwords. This is the method used in versions
prior to 1.3. If you have any passwords that were
created in this mode, or with an older version of the
server, you must either continue to use this mode, or
change to the new mode and re-enter the old passwords.
This mode is set through the Authentication Password Storage
(section 4.2.6 on page 248) configuration value. If this
value is not present (as it will not be in cases where an
older server has been upgraded but are using the same
configuration files), the default mode will be Compatible.
When a new server is installed, the configuration files that
are installed with it will specify Normalized mode.
2.15.6 Access Control Tutorial
2.15.6.1 General Information
Access control works in two modes: normal or administration
(section 2.18 on page 187). The configuration of the two
modes is the same, but uses separate access control files.
The files are:
Normal mode
Directory based configuration file (section 5.4.1 on page
343)
Administration mode
Administrative access control file (section 5.4.2 on page
344)
Note that the access control-related files, like all
configuration files, are read by the server at start-up
(section 3.2.1 on page 197) and when the server is re-
configured (section 3.3.2 on page 209). If you are
experimenting with access control and the changes do not
seem to be taking effect, re-configure the server (using the
SETWWWCFG command).
2.15.6.2 How Secure Is It?
Web Server/400 supports host filtering and Basic HTTP
authentication for controlling access to content that is
available for serving over the Web. Each kind of access
control makes it difficult, but not impossible for
unauthorized users to access protected content. Host
Page 155
Commerce Server/400 2.0 Using Commerce Server/400
filtering lets you allow or disallow access based on the
client's domain or IP address. Basic authentication lets you
require a user ID and password combination.
In Basic authentication, the user ID and password is not
sent over the network as plain text, but it is not encrypted
either. It is uuencoded, in essentially the same way as
Telnet login IDs and passwords. Basic authentication is
similar to Telnet security and is approximately as secure as
Telnet.
For maximum security, you will want to combine host
filtering and user authentication. This would force a
potential intruder to both "spoof" an IP address and to
"sniff" the network to find a valid user ID and password.
2.15.6.3 User Authentication Example
In this example, you will protect the "/WWWServ/WebDocs/Fun"
directory, only allowing access by user "DrKatz" using the
password "ProfessionalTherapist". This assumes that the
server is using the default values for the server root
(section 4.6.5 on page 274) and document root (section 4.6.2
on page 271).
. Create or modify the directory based configuration
file.
1. Ensure the file exists
The server is shipped with the stream file
"/WWWServ/Cfg/Access.Cfg". If that file is missing,
create it.
You can create a new file by copying one we ship for
this purpose: /WWWServ/Shipped/Cfg/Empty.Cfg. You
can copy this file using either the WRKLNK command
or the CPY command.
2. Ensure your master configuration file refers to your
access control file.
Enter the following command and press the F4 key:
CHGWWWCFG (section 3.3.1 on page 207)
The example above assumes that you are using the
master configuration file that was shipped with the
server. If you are not, specify the name to of the
master configuration file you are using.
Change the value of the Directory based
configuration file path parameter to the access
control file you just created:
/WWWServ/Cfg/Access.Cfg and press the enter key.
Page 156
Commerce Server/400 2.0 Using Commerce Server/400
3. Create the /WWWServ/WebDocs/Fun Directory Entry
Use the WRKWWWDIR (section 3.3.29 on page 224)
command to create a /WWWServ/WebDocs/Fun directory.
This is the directory we are going to set protection
for.
4. Set the directory values
Enter the following command and press the F4 key:
CHGWWWDIR (section 3.3.31 on page 226)
CFGFILE('/WWWServ/Cfg/WebServ.cfg')
DIRECTORY('/WWWServ/WebDocs/Fun')
Change the value of Authentication realm to 'Fun'.
This can actually be anything you want. It is passed
to the browser and the browser (usually) displays it
to the user so the user knows what they are trying
to access and therefore what user name and password
they should enter.
Change the value of Authentication type to *BASIC.
Web Server/400 currently only supports Basic
authentication.
Change the value of User file path to
'/WWWServ/Cfg/FunUsers.cfg'. This tells the server
what user file to use when evaluating access to the
current directory. You will add to the user file in
a later step.
5. Create a Limit for the get method
Use the WRKWWWLIM (section 3.3.30 on page 225)
command to add a limit for the get method and set
the require field to require user DrKatz.
When done, the file should contain a section which
looks like the one below:
<Directory /WWWServ/WebDocs/Fun>
AuthUserFile /WWWServ/Cfg/FunUsers.cfg
AuthName Fun
AuthType Basic
<Limit GET>
require user DrKatz
</Limit>
</Directory>
Note that the limit section in the example is only
restricting the GET method. You are allowed to put
multiple methods in the same limit section.
Page 157
Commerce Server/400 2.0 Using Commerce Server/400
. Add (section 3.3.25 on page 221) the "DrKatz" user to
your user file.
Enter the following command and press the F4 key:
ADDWWWUSR
As in the prior step, if you are using a different
master configuration file than the default, you will
need to enter it in the command above.
The User file path parameter should come up as
'/WWWServ/Cfg/FunUsers.cfg'. If it does not, change it.
Enter the user name DrKatz and the password
ProfessionalTherapist.
Set the Update executing RPs parameter to *IMMED. This
will update your server if it is currently running. If
the server is not running yet, start (section 3.2.1 on
page 197) it.
. Create a /WWWServ/WebDocs/Fun directory
Use the CRTDIR command to create a directory. Note that
the server user profile (section 4.13.17 on page 324)
(by default, WWWUSER) must have authority to this
directory.
. Test your changes
To test your changes, enter [host]/Fun/ in your browser
to attempt to do a dynamic index of the /Fun directory.
The browser should ask you to enter authentication
information. You will not be allowed to see the dynamic
index unless you enter DrKatz for a user name and
ProfessionalTherapist for a password.
2.15.6.4 Host Filtering Example
In this example, you will protect the same
/WWWServ/WebDocs/Fun directory, but this time, you will set
it up so that only people from the .EDU domain can access
it.
. Create or modify the directory based configuration
file.
Follow the instructions from the previous example about
how to create or modify the file, but add the following
section instead.
Page 158
Commerce Server/400 2.0 Using Commerce Server/400
<Directory /WWWServ/WebDocs/Fun>
<Limit GET>
order deny,allow
deny from all
allow from .edu
</Limit>
</Directory>
See the previous example for information about the
Limit section.
The order entry tells the server the order to evaluate
the deny and allow entries. In this example, the server
will start by denying all hosts, then allows hosts that
end in .edu.
The deny entry denies all hosts access. Both the deny
and allow entries can accept the same parameters. In
addition to the examples, you can use IP addresses or
more complete domain names.
. Ensure your master configuration file refers to your
access control file.
See the previous example for instructions about this.
Also see Protecting your AS/400 information (section 2.15 on
page 150)
2.15.7 Access Control Example
The example below assumes the directory based configuration
file contains the following entries. Note that the
indentation shown below is purely for readability. The
server will work the same way regardless of any indentation.
Page 159
Commerce Server/400 2.0 Using Commerce Server/400
<Directory />
AuthType Basic
AuthName Example
AuthUserFile /wwwserv/cfg/user.cfg
AuthGroupFile /wwwserv/cfg/group.cfg
<Limit get>
order allow,deny
allow from all
deny from .edu
</Limit>
</Directory>
<Directory /abc>
<Limit get>
order allow,deny
allow from .ncsa.edu
deny from .inetmi.com
</Limit>
</Directory>
<Directory /123>
<Limit get>
order mutual-failure
allow from .inetmi.com .net
deny from xyz.inetmi.com
</Limit>
</Directory>
<Directory /abc/def>
<Limit get>
order deny,allow
allow from hoohoo.ncsa.edu
deny from .ncsa.edu
</Limit>
</Directory>
<Directory /UserAuth>
<Limit get>
require group Development user FictionalUser1
</Limit>
</Directory>
2.15.7.1 Directory Root Example
This entry allows any host except those ending in .edu to
get documents in the root or any directory below it. The
directory entries for /abc, /abc/def, /123 and /UserAuth
contain overriding limit sections, but all other
subdirectories on the host will use this entry.
Note that the allow entry is redundant because all hosts are
allowed by default.
2.15.7.2 Directory /abc Example
This limit section still disallows hosts that end in .edu
unless they end in .ncsa.edu, in which case they are
allowed. It also disallows hosts that end in .inetmi.com.
Page 160
Commerce Server/400 2.0 Using Commerce Server/400
Except for the directory /abc/def (which contains an
overriding limit section), this limit will apply to all
subdirectories.
2.15.7.3 Directory /123 Example
Because the order in this limit section is mutual-failure,
any previous allows and denies are ignored. In this
directory (and all subdirectories), every host that ends in
.inetmi.com or .net will be allowed except for the host
xyz.inetmi.com.
2.15.7.4 Directory /abc/def Example
Note that even though this entry is not listed directly
below the /abc entry, the server will evaluate it after the
/abc directory section for any documents in /abc/def or
below. The order of directory sections within the file is
unimportant. They will always be evaluated from the root of
IFS down to the document being evaluated.
After this section is processed, any host that ends in
.ncsa.edu will not be allowed unless it is hoohoo.ncsa.edu.
Any host that ends in .inetmi.com will also not be allowed
(because of the limit section in the parent directory). All
other hosts will be allowed.
2.15.7.5 Directory UserAuth
First host filtering will be applied to allow any host
except those ending in .edu. Then user authorization will be
applied to only allow User name/password combinations for
the group Development or the user FictionalUser1.
Also see Protecting your AS/400 information (section 2.15 on
page 150)
2.15.8 How Limit Sections Are Evaluated
Limit sections can appear both within the directory based
configuration file (section 5.3.1 on page 341) and the
administrative access configuration file (section 5.4.2 on
page 344). The way that the limit sections are evaluated by
the server is identical in both cases.
If the server is evaluating access to a document that exists
in a directory for which no limit section is specified and
no parent directory has a limit section specified, access
will be granted. Otherwise, host filtering will be checked
first. If access is allowed after host filtering (this
includes the case where host filtering is not being used),
user authentication will be checked.
Page 161
Commerce Server/400 2.0 Using Commerce Server/400
2.15.8.1 Evaluating Host Filtering
When the server is evaluating whether to give access to a
document, it will work its way down the directory tree from
the IFS root, evaluating host filtering in each limit
section from the highest directory (closest to the IFS root)
to the lowest (closest to the document being evaluated).
Limit sections apply to one or more methods (client request
types).
For host filtering, the limit section directives are order
(section 4.2.16 on page 258), allow (section 4.2.2 on page
244) and deny (section 4.2.10 on page 251). The order
directive specifies the order in which the allow and deny
directives are evaluated. The allow directive is used to add
hosts which have access to a directory. The deny directive
removes hosts which have access to a directory.
For the order values allow,deny and deny,allow, each limit
section may turn access on, turn it off or do nothing.
Access will be turned on if the client's host matches an
allow entry. It will be turned off if the host matches a
deny entry. If neither the deny or allow entry matches the
client's host, access will not be changed for that limit
section. If both match the client's host, access will be set
by the last entry evaluated (this depends on the order
entry).
If order is set to mutual-failure, access will only be
allowed if the client's host matches an allow entry and does
not match a deny entry. Note that the effect of this is to
ignore any previously evaluated (higher) limit sections.
2.15.8.2 Evaluating User Authentication
To evaluate user authentication, the server will find the
limit section nearest to the document being evaluated
(farthest from the IFS root) that contains a require
(section 4.2.17 on page 259) directive. If no such limit
section is found, access will be granted.
When evaluating the require entry(ies), the current
authentication type (section 4.2.7 on page 249),
authentication user file (section 4.2.9 on page 250) and
(possibly) authentication group file (section 4.2.4 on page
246) are used. If user authentication fails, the realm
specified by the current authentication realm name (section
4.2.5 on page 247) is sent back to the browser to be
displayed to the user when the browser prompts for a user
name and password.
Also see Protecting your AS/400 information (section 2.15 on
page 150)
Page 162
Commerce Server/400 2.0 Using Commerce Server/400
2.16 Logs
Web Server/400 includes a logging facility which helps the
WebMaster maintain the server. The access log reports all
attempts to access documents on the server within either a
text file using an industry defacto standard format, or
within a Data Base file which provides a superset of the
text file information. The statistics logs (section 2.16.5
on page 170) keep track of the Web Server/400's statistics
including performance measurements, the cumulative amount of
data, and number of requests handled. There are two types of
statistics log files. The first type provides a formatted
version of calculated data within either a text file or
within a Physical File using multiple single field records
to hold the formatted text. The second type of statistics
log provided is stored within a multi-field Data Base file
containing the raw data which was used to calculate the text
version of the statistics log. The error log (section 2.16.6
on page 176) is the location that the WebMaster checks to
find any errors that may be occurring within the server.
Included within the logging facility is the ability to cycle
the log files. The log file cycling capability gives the
WebMaster the ability to set up a schedule when the error or
access (section 2.16.4 on page 166) log files should be
rotated or in the case of the statistics (section 2.16.5 on
page 170) logs, an information snapshot appended to the
file(s).
NOTE: Logging from within multiple Web Servers to the same
log file is prohibited. If the log file is locked when the
server attempts to cycle it, the cycling will be suspended
until the file is unlocked. If a tool or another instance of
the Web Server has the file open this will lock the file,
suspending the log file cycling until the file is closed
(unlocking the file).
2.16.1 Server User Profile Authority Considerations
The Server User Profile (section 4.13.17 on page 324)
requires Read, Write and eXecute authorities for all
directories containing any of the logs. Note that the
authorities assigned to all log files created, including
cycled log files will only include the *PUBLIC authorities
and the authorities of the server user profile. The *PUBLIC
authority will be assigned the same as the library or
directory where the log file exists. Any special authorities
granted or denied to other users will not be carried forward
from the library or directory. This limitation exists
because the server user profile should, in most cases, have
limited authorities for security reasons.
Page 163
Commerce Server/400 2.0 Using Commerce Server/400
2.16.2 Migration Notes for Version 1.0 Customers Logging to
Log Files within QSYS
Note: Logging within the QSYS file system has changed from
Web Server/400 version 1.0. In version 1.0 the WebMaster was
required to create the single field log file prior to
starting the server. Beginning with version 1.1 this
requirement has been removed. If the log file does not
exist, it will be created. The file formats have changed,
and the log files only support one member within them. If
multiple members exist within the file, only the first
member will be used. With the exception of the statistics
text log file, each log file stored within the QSYS file
system will use a multi-field record format. Migration from
version 1.0 to a later version will require that the
WebMaster ensure that any log files currently being logged
to the QSYS file system either be changed to a new filename,
or that the current file be deleted. The reason behind the
migration requirements is that the newer versions require a
new record format. If you are running version 1.1 or greater
of Web Server/400, the new log file will be created with the
appropriate record format.
2.16.3 Log Cycling
Access and Error Log Cycling
The access and error log files are logs that can continue to
grow with each document access. The Web Server/400's log
cycling capabilities give the WebMaster the ability to
schedule the date and time of when the contents of the
current access and error log files are copied to new files
and the current files are cleared out. With this capability
you have the ability to automatically save access and error
data to separate files for a fixed period of time. This is
particularly useful if you are using the access log file to
determine the number of times a document is accessed.
The naming algorithm used to determine the filename of the
log file containing the historical data is as follows:
QDLS file system
The QDLS file system only supports 8.3 (name.ext) names.
Given this limitation the naming algorithm used to
determine the name of the file containing the historical
data is to leave the extension the same whether one
exists or not. The eight character name will include
three digits to uniquely identify the file. The digits
will be concatenated to the name of the current log file.
If there is not enough room within the eight character
limit, the current name will be truncated to include the
three digits. The count will start at '000' incrementing
Page 164
Commerce Server/400 2.0 Using Commerce Server/400
each time to find the next highest available number
wrapping back to '000' when '999' is reached.
QSYS file system
The QSYS file system only supports ten characters within
the file name (object name). The ten character name will
include three digits to uniquely identify the file. The
digits will be concatenated to the name of the current
log file. If there is not enough room within the ten
character limit, the current name will be truncated to
include the three digits. The count will start at '000'
incrementing each time to find the next highest available
number wrapping back to '000' when '999' is reached.
All other file systems which support extended file names
(e.g. the "Root" file system)
These file systems allow more flexibility when it comes
to expanding names to include additional characters.
Three digits will be inserted into the name prior to the
last extension. These three digits will be preceded by
the '.' character and (e.g. access.log becomes
access.000.log). If the file name does not have any
extensions (no '.' included within the file) then the
three digits will be appended to the file name preceded
by the '.' character (e.g. access becomes access.000).
In addition to being able to save this information in
separate files, you are able to specify how many of these
files you want kept within the directory. The server will
search the directory for all files which match the same
naming algorithm described above. All files, which are
determined to be previous log files created by the log
cycling algorithm, are included in the count of previous
files. When the number of files determined to be previous
log files exceeds the configured value for the maximum
number of cycled log files to keep within the directory, the
earliest log files are removed. The earliest log files are
determined by the three digit numbers included within their
names not by their dates. Therefore if you wish to keep a
particular log file you must copy, move, or rename the file
in order to ensure that it is not automatically deleted by
the Web Server/400 product during log cycling.
Statistics Log Cycling
The statistics logs differ from the access and error logs in
the sense that data is only added to the statistics log
files when the logs are cycled or the server is ended. The
cycling differs in the sense that when the cycle date and
time is exceeded, the data is appended to the current file.
Statistics log cycling does not create any additional files.
All of the data is appended to the Statistics Log File
(section 4.10.7 on page 300) and the Statistics Raw Data
File (section 4.10.8 on page 301).
Page 165
Commerce Server/400 2.0 Using Commerce Server/400
Cycled Log File Security Considerations
The Server User Profile (section 4.13.17 on page 324)
requires Read, Write and eXecute authorities for all
directories containing any of the logs. Note that the
authorities assigned to all log files created, including
cycled log files will only include the *PUBLIC authorities
and the authorities of the server user profile. The *PUBLIC
authority will be assigned the same as the library or
directory where the log file exists. Any special authorities
granted or denied to other users will not be carried forward
from the library or directory. This limitation exists
because the server user profile should, in most cases, have
limited authorities for security reasons.
2.16.4 Access Log
The WebMaster uses the access log to track every attempt to
access the server, even failed attempts. This information
can be useful for many different reasons. It can be used to
determine which pages are being hit the most and perhaps
where bad links exist (in the cases where unsuccessful
attempts are reported). The access log has two different
formats. The format used is dependent upon the file system
the log is configured within. For every file system other
than the QSYS file system the log file is a text file with
its format conforming to the defacto standard put in place
by the web server industry. By following this standard
format it has made it easier for the WebMaster to obtain
industry standard tools to help analyze the data. If the log
file is configured for the QSYS file system the file is a
Data Base file which contains a superset of the data stored
within the text format. In either format if the file exists
prior to starting the server the file will be appended to.
If the file does not exist it will be created.
The access log is a file created using the Access Log
Filename (section 4.10.2 on page 294) configuration value.
Access logging can be disabled by specifying a blank access
log filename within the master configuration file, or by
specifying a '*none' value within the CHGWWWCFG (section
3.3.1 on page 207) command.
Access Log Text File Format
The following is the format of an access log entry.
Internet Address - User Name [Date and time stamp] "Req type
URL HTTP level" Status code Bytes Transferred
Internet Address
The internet address of the host machine requesting the
URL. This would be in the form of a host name if one is
available.
Page 166
Commerce Server/400 2.0 Using Commerce Server/400
User Name
The user name passed in the authentication header of the
request.
Date and Time stamp
The format of the date and time stamp is
[DD/Mth/Year:hr:mi:ss +-GMT] where
. DD is the day of the month
. Mth is the month
. Year is the year
. hr is the hour displayed as a value (0 - 23 hours)
. mi is the minutes
. ss is the seconds
. GMT will be the difference in time between the
current time zone set on the AS/400 and Greenwich
Mean Time. The first character in this field
represents whether the current time zone is ahead
(+) or behind (-) GMT. The next 4 characters
represent the offset in hours and minutes HHMM.
Req type
The type of request being logged.
URL
The Uniform Resource Locator requested to be processed.
HTTP level
The HTTP protocol level requested by the browser. If
there is no value in this location the requesting
browsers HTTP protocol contains a level prior to HTTP/1.0
level (0.9 is the only valid HTTP protocol documented
prior to 1.0).
Status code
The status code (section 2.9.6 on page 114) resulting
from the attempt to access the URL specified. For example
200 indicates that the request was successfully processed
without errors.
Bytes transferred
The size of the URL transferred to fulfill the request.
Access Log Data Base File Format
The data base format of the access log is very similar to
the text formatted log file in the sense that it contains a
single record for each attempted document access and it
includes a superset of the data available in the text log
file. The field ordering of the data base version of the
access log file differs from the text formatted version. The
following is the format of the data base version of an
access log entry.
Page 167
Commerce Server/400 2.0 Using Commerce Server/400
Short Internet Address - User Name Date Time [Date and time
stamp] Status code Bytes Transferred "Req type URL HTTP
level" Long Internet Host Name
Short Internet Address (32 characters)
The internet address of the host machine requesting the
URL. This would be in the form of a host name if one is
available. This field only contains the first 32
characters of the host name. The entire host name is
supplied in the Long Internet Host Name field.
User Name (10 characters)
The user name passed in the HTTP authentication header of
the request.
Date (8 characters)
This is the current access request date specified in the
current time zone versus the GMT time zone. The format of
this field is "YYYYMMDD"
. YYYY is the year using 4 character positions
. MM is the month using 2 character positions
. DD is the day of the month using 2 character
positions.
Time (6 characters)
This is the current access request time specified in the
current time zone versus the GMT time zone. The format of
this field is "HHMMSS"
. HH is the hour displayed as a value of (00 - 23
hours) using 2 character positions
. MM is the minutes using 2 character positions
. SS is the seconds using 2 character positions
Date and Time stamp (28 characters)
The access request date and time specified using the
access log industry standard format (including the fact
that the date and time is specified in Greenwich Mean
Time (GMT)). The format of the date and time stamp is
[DD/MM/YYYY:HH:MM:SS +-GMT] where
. DD is the day of the month using 2 character
positions
. MM is the month using 2 character positions
. YYYY is the year using 4 character positions
. HH is the hour displayed as a value of (0 - 23
hours) using 2 characters positions
. MM is the minutes using 2 character positions
. SS is the seconds using 2 character positions
. GMT will be the difference in time between the
current time zone set on the AS/400 and Greenwich
Mean Time (GMT) using 5 character positions. The
first character in this field represents whether the
current time zone is ahead (+) or behind (-) GMT.
The next 4 characters represent the offset in hours
and minutes HHMM.
Page 168
Commerce Server/400 2.0 Using Commerce Server/400
Status code (3 characters)
The status code (section 2.9.6 on page 114) resulting
from the attempt to access the URL specified. For example
200 indicates that the request was successfully processed
without errors.
Bytes transferred (10 characters)
The size of the URL transferred to fulfill the request.
Req method type (6 characters)
The HTTP request method type being logged (Get, Post, Put
or Delete).
HTTP level (10 characters)
The HTTP protocol level requested by the browser. If
there is no value in this location the requesting
browsers HTTP protocol contains a level prior to HTTP/1.0
level (0.9 is the only valid HTTP protocol documented
prior to 1.0).
URL (128 characters)
The Uniform Resource Locator requested to be processed.
Long Internet Address (128 characters)
The internet address of the host machine requesting the
URL. This would be in the form of a host name if one is
available. This field supports the entire host name. The
short internet address only contains the first 32
characters. In the cases where the host name is longer
than 32 characters this field would be the location to
find the entire name.
The differences between the text access log file and the
data base access log file are described by the additional
fields listed below.
. The date and time of the access attempt is recorded
using the current time zone values (not GMT). This
information is supplied separating the date and time
into two separate fields.
. A long and short version of the host name are both
available. The long host name field which can hold up
to 128 characters is located at the end of the record,
while a short version (holding only the first 32
characters of the host name) is recorded in the first
field of the record. The shortened host name is located
in the front of the record for two reasons, the first
is to make the host name or internet address easily
available to the WebMaster when viewing the file using
the DSPPFM command or the Web Server/400's integrated
data base access support. Secondly it is kept in the
same location as the text file format, this is for the
WebMaster who is accustomed to viewing the text based
Page 169
Commerce Server/400 2.0 Using Commerce Server/400
industry standard access log. The long host name field
is located as the last field in the record. This field
will include the entire name, and is only needed when
the name exceeds 32 characters.
The DDS source used to create the access log can be found in
the WWWSERVER library QDDSSRC file ACCESSLOG member. This
information can be used to programmatically describe the
record format of the access log data base file.
The Server User Profile (section 4.13.17 on page 324)
requires Read, Write and eXecute authorities for the
directory containing the access log file.
2.16.5 Statistics Logs
There are two different Web Server/400 statistics log files
available:
. A text file containing the calculated statistics log
file configured using the Statistics Log Filename (Logs
on page 240) configuration value.
. A multiple field data base file containing the raw data
used to calculate the text version of the statistics
log file. The Statistics Raw Data Log Filename
configuration value is used to configure this filename.
2.16.5.1 Statistics Log File (calculated values)
The text version of the statistics log file contains four
tables of formatted and calculated information:
Request Processor Averages
The following is the format of the table. Each row
represents the statistics for one Request Processor.
RP Req/ Bytes/ CPU Time/ Elapsed Time/ Avg.
Bytes Avg. Bytes
Nbr Sec. Sec. Req(secs) Req(secs)
Sent/Req Rcv/Req
--- ------ -------- ---------- ------------- ----
------ ----------
1 x.xx xx.xx K x.xx xx.xx
xx.xx K xx.xx K
2 y.yy yy.yy M x.xx yy.yy
yy.yy M yy.yy M
RP Nbr
Request Processor Number
Page 170
Commerce Server/400 2.0 Using Commerce Server/400
Req/Sec.
The number of Requests/Second processed by each request
processor. The time measurement used to calculate the
result is based on elapsed time.
Bytes/Sec.
The average amount of data processed by the request
processor each second. The time measurement used to
calculate the result is based on elapsed time.
CPU Time/Req (secs)
The average amount of CPU processing time incurred
processing each request (measured in seconds).
Elapsed Time/Req (secs)
The average amount of elapsed time incurred processing
each request (measured in seconds).
Avg. Bytes Sent/Req
The average amount of data sent for each request.
Avg. Bytes Rcv/Req
The average amount of data received for each request.
Request Processor Totals
The following is the format of the table. Each row
represents the statistics for one Request Processor.
RP Number CPU Req Elapsed Req Bytes
Bytes
Nbr of Req Time(secs) Time(secs) Sent
Received
--- -------- ---------- ----------- --------- ---
-------
1 xxx.x K x.xx x.xx xx.xx K
xx.xx K
2 yyy.y M y.yy y.yy yy.yy M
yy.yy M
RP Nbr
Request Processor Number
Number of Req
The total number of requests processed.
CPU Req Time (secs)
The total amount of CPU time spent processing all the
requests.
Elapsed Req Time secs)
The total amount of elapsed time spent processing all
the requests.
Page 171
Commerce Server/400 2.0 Using Commerce Server/400
Bytes Sent
The total amount of data sent for all the requests.
Bytes Received
The total amount of data received for all the requests.
Request Processor Calendar Information
The following is the format of the table. Each row
represents the start and end date and time for one
Request Processor.
RP
Nbr Start Time End Time
--- -------------------- --------------------
1 dd/mth/year dd:mi:ss dd/mth/year dd:mi:ss
2 dd/mth/year dd:mi:ss dd/mth/year dd:mi:ss
RP Nbr
Request Processor Number
Start Time
The date and time the request processor was started.
End Time
The date and time the request processor ended.
Server Totals
The following is the format of the table.
Start Time . . . . . . . . . . . . . . . . :
dd/mth/year dd:mi:ss
End Time . . . . . . . . . . . . . . . . . :
dd/mth/year dd:mi:ss
Total Number of Requests . . . . . . . . . : x
Requests/Second . . . . . . . . . . . . . : x.xx
Average CPU Processing Time per Request . : x.xxx
(seconds)
Total CPU Processing Time . . . . . . . . : xx.xx
(seconds)
Average Elapsed Time per Request . . . . . : x.xxx
(seconds)
Total Elapsed Time . . . . . . . . . . . . : xx.xx
(seconds)
Average Bytes Sent per Request . . . . . . : xxxx.xx
Total Bytes Sent . . . . . . . . . . . . . : xxxxx
Average Bytes Received per Request . . . . : xxx.xx
Total Bytes Received . . . . . . . . . . . : xxx
Bytes/Second . . . . . . . . . . . . . . . : xxx.xx
Total Bytes . . . . . . . . . . . . . . . : xxxxx
Start Time
The date and time the Web Server was started.
Page 172
Commerce Server/400 2.0 Using Commerce Server/400
End Time
The date and time the Web Server ended.
Total Number of Requests
The total number of requests processed by all of the
request processors during this run of the web server.
Requests/Second
The total number of Requests/Second processed by all of
the request processors. The time measurement used to
calculate the result was based on the total elapsed
time required to process the requests.
Average CPU Processing Time per Request
The average amount of CPU processing time required per
request.
Total CPU Processing Time
The total amount of CPU processing time required to
process all of the requests.
Average Elapsed Time per Request
The average amount of elapsed time required per
request.
Total Elapsed Processing Time
The total amount of elapsed time required to process
all of the requests.
Average Bytes Sent per Request
The average amount of data sent for each request.
Total Bytes Sent
The total amount of data sent by all request
processors.
Average Bytes Received per Request
The average amount of data received for each request.
Total Bytes Received
The total amount of data received by all request
processors.
Bytes/Second
The average amount of data processed by the request
processors each second. The time measurement used to
calculate the result was based on the total elapsed
time required to process the requests.
Total Bytes
The total amount of data sent and received by all
request processors.
The following notes apply to all of the tables:
Page 173
Commerce Server/400 2.0 Using Commerce Server/400
. Start and End Time format legend: dd - day, mth -
month, year - year, hr - hour, mi - minutes, ss -
seconds
. All measurements of bytes (bytes sent, bytes received,
and total bytes) with "K" or "M" multipliers refer to
computer calculations of these values where K = 1024
and M = 1024x1024. Measurements that don't deal with
bytes that include a "K" or "M" multipliers refer to
the following values K = 1000 and M = 1,000,000.
Note: If the text version of the statistics log file is
stored within the QSYS file system it will contain a single
field record format. The information stored within the file
will look the same as if it were in any other file system.
2.16.5.2 Statistics Raw Data Log File
The statistics raw data log file contains a multiple field
record format. The DDS source used to create the statistics
raw data log can be found in the WWWSERVER library QDDSSRC
file STATSLOG member. This information can be used to
programmatically describe the record format of the
statistics raw data log data base file. This file can be
used as the basis for creating a Web Server/400 statistics
tool or CGI script.
The statistics raw data log file includes a record for each
Request Processor. This log file contains two types of
records, intermediate and total. The records written during
the cycling of the statistics log file are considered
intermediate records. The records written at the end of a
server run are considered total records. The following is
the list of the fields, in their respective order, included
within a statistics raw data log data base file entry:
Intermediate or Total statistics flag (1 character)
The statistics raw data log file includes records written
during the cycling of the statistics log (intermediate
statistics) or at the end of the server run (total
statistics). A value of '0' indicates an intermediate
statistics record and a value of '1' indicates a total
statistics record.
Port Identifier (5 characters)
The port identifier indicates the port the request
processor recording these statistics is running on.
Request Processor Number (5 characters)
The request processor identifier.
Statistics Date (8 characters)
The date when this record was written to the statistics
raw data log file. The format of this field is "YYYYMMDD"
. YYYY is the year using 4 character positions
Page 174
Commerce Server/400 2.0 Using Commerce Server/400
. MM is the month using 2 character positions
. DD is the day of the month using 2 character
positions.
Statistics Time (6 characters)
The time when this record was written to the statistics
raw data log file. The format of this field is "HHMMSS"
. HH is the hour displayed as a value of (00 - 23
hours) using 2 character positions
. MM is the minutes using 2 character positions
. SS is the seconds using 2 character positions
Start Date (8 characters)
The date when the request processor reporting these
statistics was started. The format of this field is
"YYYYMMDD"
. YYYY is the year using 4 character positions
. MM is the month using 2 character positions
. DD is the day of the month using 2 character
positions.
Start Time (6 characters)
The time when the request processor reporting these
statistics was started. The format of this field is
"HHMMSS"
. HH is the hour displayed as a value of (00 - 23
hours) using 2 character positions
. MM is the minutes using 2 character positions
. SS is the seconds using 2 character positions
End Date (8 characters)
The date when the request processor reporting these
statistics ended. The format of this field is "YYYYMMDD"
. YYYY is the year using 4 character positions
. MM is the month using 2 character positions
. DD is the day of the month using 2 character
positions.
End Time (6 characters)
The time when the request processor reporting these
statistics ended. The format of this field is "HHMMSS"
. HH is the hour displayed as a value of (00 - 23
hours) using 2 character positions
. MM is the minutes using 2 character positions
. SS is the seconds using 2 character positions
Number of Requests
The number of requests processed by this request
processor. For intermediate records this data indicates
the number of requests since the last intermediate
record. For total records this data indicates the total
number of requests processed during this run of the
server.
Page 175
Commerce Server/400 2.0 Using Commerce Server/400
CPU Processing Time
The amount of CPU time used by this request processor.
For intermediate records this data indicates the amount
of CPU time since the last intermediate record. For total
records this data indicates the total amount of CPU time
used by this request processor during this run of the
server.
Elapsed Time
The amount of elapsed time spent processing requests. For
intermediate records this data indicates the amount of
elapsed time since the last intermediate record. For
total records this data indicates the total amount of
elapsed time used by this request processor during this
run of the server.
Bytes Sent
The total amount of data sent by the request processor.
For intermediate records this data indicates the number
of bytes sent since the last intermediate record. For
total records this data indicates the total amount of
data sent by this request processor during this run of
the server.
Bytes Received
The total amount of data received by the request
processor. For intermediate records this data indicates
the number of bytes received since the last intermediate
record. For total records this data indicates the total
amount of data received by this request processor during
this run of the server.
The Server User Profile (section 4.13.17 on page 324)
requires Read, Write and eXecute authorities for the
directories containing the statistics log files.
2.16.6 Error Log
The error logging facility is used by the Webmaster to
determine what web server errors are occurring on the
system. These errors may include, but are not limited to
system errors, TCP/IP errors, and programming errors.
The error log has two different formats. The format used is
dependent upon the file system the log is configured for.
For every file system other than the QSYS file system the
log file is a text file. Within the QSYS file system the log
entries are stored within a multiple field data base file.
The Error Log Filename configuration value is used to
configure the error log file.
There are three levels of logging: Error, Warning,
Informational. The Error level of logging is the most severe
level of the three with the Informational level being the
Page 176
Commerce Server/400 2.0 Using Commerce Server/400
least severe. The WebMaster has the ability to indicate what
level of error messages to be placed in the error log file
through the configuration value Error Log Level (section
4.10.5 on page 298).
Error
These messages are most often messages that need to be
addressed.
Warning
These messages are possible areas to be aware of.
Informational
These messages are pieces of information that may help
your server run smoother, but may not be a major concern.
The following is the format of the error log text file
entries:
[day-of-week month day time year] Program name reporting
error: Level of error message: Error message text
The following is the list of the fields, in their respective
order, included within a data base error log file entry:
Date (8 characters)
This is the date when the error occurred. The format of
this field is "YYYYMMDD"
. YYYY is the year using 4 character positions
. MM is the month using 2 character positions
. DD is the day of the month using 2 character
positions.
Time (6 characters)
This is the time when the error occurred. The format of
this field is "HHMMSS"
. HH is the hour displayed as a value of (00 - 23
hours) using 2 character positions
. MM is the minutes using 2 character positions
. SS is the seconds using 2 character positions
Program name reporting the error (10 characters)
The name of the program reporting the error. The Web
Server/400 product ships multiple programs with the
product. This name is used to determine which program the
error occurred within.
Error level (2 characters)
The level of the error log entry. The valid values are 10
(indicating an informational message), 30 (indicating a
warning message) or 40 (indicating an error message).
Error message text (512 characters)
The error message text.
Page 177
Commerce Server/400 2.0 Using Commerce Server/400
The Server User Profile (section 4.13.17 on page 324)
requires Read, Write and eXecute authorities for the
directory containing the error log file.
Page 178
Commerce Server/400 2.0 Using Commerce Server/400
2.17 Server-Side Includes
2.17.1 What are Server-Side Includes?
A server-side include is a type of macro that can be
expanded at the time the Web server is sending the document
to the browser. Special tags embedded in an HTML document
are recognized as instructions to the server to perform a
substitution for the tag. The substitution depends on the
tag. The supported tags include echo, include, exec, config,
fsize, and flastmod. With these tags, another document can
be included inline, the output of a script can be included,
a file's last modification date and time can be included,
and more.
2.17.2 Which Files are Parsed?
All files are not searched for Server-side includes. A
slight performance penalty exists for doing this parsing.
Only files with a certain content type are parsed before
they are sent. This content type is text/x-server-parsed-
html. A typical setup (and the default setup) is to have the
extensions .SHTML and .SHT map to the content type text/x-
server-parsed-html. This means that only files with that
extension are parsed for server-side includes.
IFS files, QDLS files, spooled files and database files can
all contain server-side includes. The header and footer
files for spooled files and database files can also include
server-side includes. However, the header and footer files
for dynamic indexes will send a server-side include file as
a regular HTML file.
2.17.3 Server-Side Include Format
The format of a server-side include is as follows:
<!--#tag parm1="value1" parm2="value2" ... -->
where,
<!--#
These five characters always begin a server-side include.
This will hide the command as a comment if the file ends
up on a Web server that does not support server-side
includes.
Page 179
Commerce Server/400 2.0 Using Commerce Server/400
tag
The tag indicates the type of server-side include to
perform. Valid values are echo, include, exec, config,
fsize, and flastmod. Tags are not case-sensitive. Each
tag is described below.
parmX="valueX"
Each tag has one or more parameters that are specified as
parm="value". If multiple parameters are specified, each
is separated by a space. The parameter name is not case-
sensitive, but the value might be depending on the
parameter and operation.
-->
A server-side include always ends with these three
characters.
2.17.3.1 Example Include
The following document will include the Internet host name
of the machine that serves this document.
<HTML>
<BODY>
This document is being served by <!--#echo
var="SERVER_NAME"-->.
</HTML>
</BODY>
Example output:
This document is being served by www.inetmi.com.
2.17.4 Supported Tags
Below is a list of the different operations a server-side
include can perform. Each tag and its parameters are
described.
ECHO
The echo server-side include is replaced with the value of a
pre-defined variable that is specified as a parameter. The
only valid parameter is var.
The echo command is used to send the value of several pre-
defined variables to the browser. These variables include
all the pseudo-environment variables available to script
programs and some just available to server-side include
documents.
. Script Pseudo-Environment Variables (Server Supplied on
page 104)
Page 180
Commerce Server/400 2.0 Using Commerce Server/400
All of the environment variables that are available to
Web Server/400 scripts are also available through the
echo server-side include.
. Server-Side Include Variables
The following lists the additional variables that are
available for including in server-side include
documents.
. DOCUMENT_NAME
The fully qualified path of the document currently
being parsed.
. DOCUMENT_URI
The URL-path (URL-path on page 54) entered to
request this document. The URL-path is still
escaped. The query string is not part of this value.
. QUERY_STRING_UNESCAPED
The query string used to request this document. The
query string is already unescaped.
. DATE_LOCAL
The current local date and time. The format of the
date and time can be configured using the timefmt
parameter of the config server-side include tag.
This format string can contain meta-symbols (section
2.17.5 on page 186) that describe how the date and
time are displayed. The default string is "%a %b %d
%H:%M:%S %Y" which produces a date and time string
of "Wed Jan 15 14:21:45 1992".
. DATE_GMT
This is the same as DATE_LOCAL except in Greenwich
Mean Time.
. LAST_MODIFIED
The local date and time the current document was
last modified. This is presented the same as
DATE_LOCAL.
. Statistic Variables
The following variables are available to include
information about the usage and performance statistics
of the current Web Server. These values are updated for
each new document.
. STATS_START_TIME
The date and time the server was started in local
time.
. STATS_TOTAL_REQUESTS
The number of requests the server has handled since
it was started.
Page 181
Commerce Server/400 2.0 Using Commerce Server/400
. STATS_REQUESTS_SECOND
The average number of requests served per second.
. STATS_AVG_CPU_REQUEST_TIME
The average CPU time spent per request.
. STATS_TOTAL_CPU_REQUEST_TIME
The total CPU time spent handling all the requests.
. STATS_AVG_ELAPSED_REQUEST_TIME
The average elapsed (wall) time spent per request.
. STATS_TOTAL_ELAPSED_REQUEST_TIME
The total elapsed (wall) time spent handling all the
requests.
. STATS_AVG_BYTES_SENT
The average number of bytes sent per request.
. STATS_TOTAL_BYTES_SENT
The total number of bytes sent for all requests.
. STATS_AVG_BYTES_RCVD
The average number of bytes received per request.
. STATS_TOTAL_BYTES_RCVD
The total number of bytes received for all requests.
. STATS_TOTAL_BYTES
The total number of bytes send and received for all
requests.
. STATS_AVG_BYTES_PER_SECOND
The average number of bytes transmitted per second.
. STATS_TOTAL_NUM_RPS
The number of request processors currently handling
requests on the server.
INCLUDE
The include server-side include allows one document to
include another document. The main document and its included
sub-documents are all sent as one large document to the
browser.
Included files can themselves include other files. The level
of nesting has no limit. However, circular references are
not allowed. For instance, if Document A includes Document B
which includes Document A again, an error will occur.
Any type of URL can be included except script (section 2.9
on page 102) URLs. This includes dynamic indexes, database
files, user directory files, and spooled files.
Page 182
Commerce Server/400 2.0 Using Commerce Server/400
The document to include can be specified in one of two ways:
. File
The include tag can have a file parameter that
specifies a file to include. The format of an include
of a file is:
<!--#include file="RelativeFilename"-->
The "RelativeFilename" is the name of the file to
include. The path of the included file is relative to
the current file. The path cannot contain any parent
directory references ("../") and it cannot start with a
slash.
. Virtual
The include tag can have a virtual parameter that
specifies a new URL to include. The format of an
include of a virtual is:
<!--#include virtual="NewURL"-->
The "NewURL" is the new URL to include. This can
include the URL-path (URL-path on page 54) and query
string (Query String on page 54) portions of a URL.
This new URL is resolved as if it was a request by
itself.
EXEC
The exec server-side include is used to insert the output
from a script (section 2.9 on page 102) into a parsed
document. Any valid CGI script can be included, however the
output of some scripts is not appropriate for inclusion in
the middle of another HTML document. For instance, a script
might have its own <HEAD> section even though the main
document already contains a <HEAD> section.
Any response headers (Response Headers on page 111) returned
by the script are not included in the resulting document,
but are still necessary for proper interpretation of the
script output.
If the result of the CGI script is a redirection (Location
on page 113), then a hyperlink to the redirected location is
inserted in the document instead of the output of the
script.
The only valid parameter to exec is:
. cgi
The cgi tag indicates the virtual path of the script to
execute. This value is the same as the value of the
Page 183
Commerce Server/400 2.0 Using Commerce Server/400
virtual parameter to the include tag except that it can
only point to a script.
<!--#exec cgi="ScriptURL"-->
The "ScriptURL" is the URL of the script to execute.
CONFIG
The config server-side include is used to configure the
behavior of server-side includes. This includes changing the
default error message, the time format, and the file size
format. Configuration changes take effect immediately and
last until the end of the document or until the
configuration value is changed again.
. errmsg
Whenever an error occurs parsing a server-side include
file, this error message is sent in-line in the
document. The errmsg config parameter changes the
default error message to any valid string. Any error
that occurs after this configuration tag will produce
the new message.
<!--#config errmsg="Error message"-->
. timefmt
Many values displayed when parsing a server-side
include document include dates and times. These values
are displayed using the timefmt format string. This
string can contain meta-symbols that describe how the
date and time are displayed. The default string is "%a
%b %d %H:%M:%S %Y" which produces a date and time
string of "Wed Jan 15 14:21:45 1992".
<!--#config timefmt="meta-string"-->
The "meta-string" includes regular characters and meta-
symbols that are used to describe the format of the
date and time being displayed.
. sizefmt
Some server-side includes display file sizes. This
value configures how those sizes are displayed.
<!--#config sizefmt="SizeFormat"-->
The "SizeFormat" can be either "bytes" or "abbrev". A
value of bytes indicates the size should be displayed
as the decimal number of bytes in a file. A value of
abbrev indicates the size should be displayed in bytes,
kilobytes, megabytes or gigabytes. For example, a file
containing 4678 bytes would be displayed as 4K in
abbrev mode. The size format defaults to bytes.
Page 184
Commerce Server/400 2.0 Using Commerce Server/400
FSIZE
The FSIZE server-side include expands to the size of a
specified file. The size is displayed as configured by the
sizefmt parameter to the config tag.
The target file can be specified in one of two ways:
. File
The fsize tag can have a file parameter that specifies
a target file. The format of a fsize of a file is:
<!--#fsize file="RelativeFilename"-->
The "RelativeFilename" is the name of the target file.
The path of the file is relative to the current file.
The path cannot contain any parent directory references
("../") and it cannot start with a slash.
. Virtual
The fsize tag can have a virtual parameter that
specifies a new URL of the target file. The format of a
fsize of a virtual is:
<!--#fsize virtual="NewURL"-->
The "NewURL" is the new URL of the target file. This
should be a full URL-path (URL-path on page 54). This
new URL is resolved as if it was a request by itself.
FLASTMOD
The FLASTMOD server-side include expands to the last
modification date and time of a specified file. The last
modification date and time are displayed as configured by
the timefmt parameter to the config tag.
The target file can be specified in one of two ways:
. File
The flastmod tag can have a file parameter that
specifies the target file. The format of a flastmod of
a file is:
<!--#flastmod file="RelativeFilename"-->
The "RelativeFilename" is the name of the target file.
The path of the file is relative to the current file.
The path cannot contain any parent directory references
("../") and it cannot start with a slash.
. Virtual
The flastmod tag can have a virtual parameter that
specifies a new URL of the target file. The format of a
flastmod of a virtual is:
Page 185
Commerce Server/400 2.0 Using Commerce Server/400
<!--#flastmod virtual="NewURL"-->
The "NewURL" is the new URL of the target file. This
should be a full URL-path (URL-path on page 54). This
new URL is resolved as if it was a request by itself.
2.17.5 Time Format Special Characters
Below are the special characters that can be used to create
a custom date and time string. These characters are replaced
with their date or time element. Other characters in the
format string are copied verbatim. The resulting time stamp
cannot be longer than 255 characters.
Meta
Symbol Date or Time Element
------ -----------------------------------------------
-
%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%c Date and time representation
%d Day of the month (01-31)
%H Hour in 24-hour clock (00-23)
%I Hour in 12-hour clock (01-12)
%j Day of the year (001-366)
%m Month (01-12)
%M Minute (00-59)
%p AM or PM
%S Second (00-61)
%U Week number of year (begins with Sunday) (00-
53)
%w Weekday (0-6) where Sunday is 0
%W Week number of year (begins with Monday) (00-
53)
%x Date representation
%X Time representation
%y Year without the century (00-99)
%Y Tear
%Z Name of time zone
%% A percent character ("%")
Page 186
Commerce Server/400 2.0 Using Commerce Server/400
2.18 Administration Mode
2.18.1 What is the Administration Mode?
The Administration Mode provides a friendly view of the
information that constitutes your Web site. It allows easy
access to current configuration values, files that make up
the content, access logs, error logs, dynamic performance
statistics, and more. All of this is available through your
Web browser.
Through a special URL and special protection mechanisms, an
administrator can view any of the above information at any
time. You can set this up to be available from a Web browser
on any host machine or only from certain host machines. You
can also protect this mode using user IDs and passwords.
AS/400 object authority is also used to limit access. If the
Server User Profile does not have authority to a file,
directory, or library accessed through administration mode,
then the server will not be able to serve data from that
location even in this special mode.
Important: Because the Administration Mode of Web Server/400
provides so much access to the information related to your
Web site and information stored on your AS/400, it is by
default disabled. Administration mode can be easily enabled,
piece-by-piece, through the administrative access control
configuration file. See below for instructions (Enabling
Administration Mode on page 189) on how to do this.
2.18.1.1 Administration Mode Main Menu
An HTML document is available as a starting point for access
to all that the administration mode has to offer. This is an
HTML document that can be viewed through a Web browser. It
contains links to pertinent information. Once the Web server
has been configured to enable administration mode, this menu
can be accessed by entering the following URL:
http://www.server.com/wwwadmin (/wwwadmin)
The www.server.com portion is the host address of the
machine running the Web server. The wwwadmin portion is the
special URL that puts Web Server/400 into administration
mode. If nothing follows this portion of the URL, then the
main menu is displayed. More path information can be
included after the wwwadmin. See below (Administration Mode
URL Access on page 188) for what effect this has.
Page 187
Commerce Server/400 2.0 Using Commerce Server/400
Note: A subdirectory with the name wwwadmin off of the
Document Root cannot be easily accessed and should be
avoided.
Below is a description of what is available through the
administration mode. The main menu consists of links to all
this information. Some values can be configured to limit
access. Selecting the restricted links will result in a
forbidden or unauthorized message being displayed.
. Log Files
All the currently configured log files (access logs,
error logs, and statistics logs) can be easily accessed
through convenient links. An index of all the log files
in the directory that contains the access log can also
be easily viewed.
. Configuration Files
The configuration values that are currently being used
by the Web server can easily be viewed through
hyperlinks. These include the master configuration
file, the directory based configuration file, the
administration mode access control file, the alias
configuration file, the content type configuration
file, and the imagemap configuration file.
. Content Files
Any file stored under any of the Document Roots can
easily be accessed. Using this, the Index Name files
are not displayed so dynamic indexes are always
displayed to view all the files in a particular
directory.
. Graphical View of IFS
In addition to the Document Roots, the administration
mode can be set up to access any directory under the
Integrated File System.
. Dynamic Performance Statistics
The administration mode also provides a view of the
dynamically calculated statistics of the Web server.
2.18.1.2 Administration Mode URL Access
The main menu can be bypassed and the content accessed
directly with URLs that have the following form:
http://www.server.com/wwwadmin/URL-path
If a URL-path (URL-path on page 54) follows the wwwadmin
keyword, then that path is treated as a regular URL-path
except the path is taken relative to the root of IFS instead
of relative to the root of the appropriate Document Root.
Most any valid URL-path is treated the same as if it were
Page 188
Commerce Server/400 2.0 Using Commerce Server/400
entered without the wwwadmin keyword. User directories,
database files, scripts, and so forth are all available
through the administration mode if they follow the wwwadmin
keyword. Three main differences exist.
1.Paths are relative to the root of IFS instead of
relative to a document root.
2.A dynamic index is always displayed when a directory is
requested even if an Index Name exists in that
directory. This provides greater access to the Web
content in the directory.
3.Aliases are not expanded since aliases are relative to
a document root but URL-paths are relative to the root
of IFS in administration mode.
Since entering an empty URL-path results in the main menu,
the query string Root is available to get a dynamic index of
the root of IFS:
http://www.server.com/wwwadmin/?Root
2.18.1.3 Enabling Administration Mode
As a security precaution, administration mode is disabled in
the default installation. Each installation that chooses to
enable administration mode must perform the following steps.
NOTE: Users who are upgrading from version 1.1 and have not
configured administration mode before, will need to remove
the first line from the AdUser.cfg file listed below. This
can be done by editing the AdUser.cfg file using a PC
editor. Or, a new source physical file can be created (using
CRTSRCPF) that is empty. The path of this source physical
file (e.g., /QSYS.lib/MyLibrary.lib/MyFile.file/MyMbr.mbr)
should then be used instead of /WWWServ/Cfg/AdUser.cfg.
Simple Steps for Configuring Administration Mode
1.Change the Administrative Access Control Configuration
Use the WRKWWWDIR command with the *ADMIN parameter to
enable administrative access mode. Use option 2 to
change the directory configuration values for the root
directory ("/"). Change the User file path to
/WWWServ/Cfg/AdUser.cfg. Press enter to apply the
change.
2.Change the Access Limits
While still in the WRKWWWDIR command, use option 6 to
work with limits. Use option 5 (Work with
allow/deny/require) on the existing Access methods
entry to modify the access limitations.
Page 189
Commerce Server/400 2.0 Using Commerce Server/400
. Add, using option 1, a require entry. Keyword =
require, Value = user WWWAdmin
The require entry says that the user must
authenticate themselves as WWWAdmin before the
administration mode can be accessed. Note that
WWWAdmin can be any name.
. Remove, using option 4, the deny all entry.
If this entry is not removed, all hosts are
prohibited from accessing the administrative mode.
You could change this to only allow accesses from
your domain in addition to requiring a user ID and
password.
3.Add an Administrator User to the User File
One of the above steps sets the User file path to
/WWWServ/Cfg/AdUser.cfg. By default, this file has no
users in it. Add the user name entered on the require
entry in the above step to this file (WWWAdmin). To add
this user, along with a good password, use the command
WRKWWWUSR (section 3.3.24 on page 221) or ADDWWWUSR
(section 3.3.25 on page 221).
4.Start the Server or Reconfigure a Running Server
If the Web server is not currently running, start the
server and the administration mode should be available.
If the server is currently running, reconfigure the
server by issuing the SETWWWCFG command.
If you prefer, the file /WWWServ/Cfg/AdAccess.cfg can be
edited directly with a stream file editor. Change the lines
found at the end of this file to be as follows.
<Directory />
AuthName WebServerAdmin
AuthType Basic
AuthUserFile /WWWServ/Cfg/AdUser.cfg
<Limit GET PUT POST DELETE HEAD>
require user WWWAdmin
</Limit>
</Directory>
The next time the server is started or re-configured,
administration mode will be accessible to those who can
authenticate themselves as an administrator for this Web
site.
Advanced Steps for Configuring Administration Mode
Note that the above configuration changes make all data on
your AS/400 that the Server User Profile has access to
Page 190
Commerce Server/400 2.0 Using Commerce Server/400
available to those who can authenticate themselves properly.
A more conservative setup would change the configuration to
limit access to the current Server Root and its
subdirectories only. The example below only allows users
from the inetmi.com domain with the password for WWWAdmin to
access files stored in the default Server Root and its
subdirectories (but no other locations). All other users
would be denied all access to the administrative mode.
The below discussion outlines the steps needed to set up the
server to use this more elaborate configuration. Not all
steps are given in detail. In addition to the following, a
user and password needs to be added to the
/WWWServ/Cfg/AdUser.cfg file.
1.Add directory / using WRKWWWDIR. To prevent everyone
from getting to the root directory and below, change
this directory to have the following configuration
values:
Authentication realm: WebServerAdmin
Authentication type *BASIC
User file path /WWWServ/Cfg/AdUser.cfg
Group file path *INHERIT
Add a limit for GET POST PUT DELETE HEAD. Under this
limit, add a deny all entry.
2.Add directory /WWWServ using WRKWWWDIR. This
subdirectory will inherit the correct realm, type, and
user file path from the root ("/") directory.
Add a limit for GET POST. Change the limit order to be
deny,allow. Under this limit, add a deny all entry, an
allow .inetmi.com entry, and a require user WWWAdmin
entry. This will only allow access to users from the
inetmi.com domain that can provide the correct password
for WWWAdmin.
3.Add directory /*META/ADMIN_MENU using WRKWWWDIR. This
META directory will inherit the correct realm, type,
and user file path from the root ("/") directory.
Add a limit for GET POST. Change the limit order to be
deny,allow. Under this limit, add a deny all entry, an
allow .inetmi.com entry, and a require user WWWAdmin
entry. This will only allow users from the inetmi.com
domain that can provide the correct password for
WWWAdmin to receive the administration mode main menu.
If you prefer, the file /WWWServ/Cfg/AdAccess.cfg can be
edited directly with a stream file editor. The following
lines are equivalent to the configuration described above.
Page 191
Commerce Server/400 2.0 Using Commerce Server/400
<Directory />
AuthName WebServerAdmin
AuthType Basic
AuthUserFile /WWWServ/Cfg/AdUser.cfg
<Limit GET POST PUT DELETE HEAD>
deny from all
</Limit>
</Directory>
<Directory /WWWServ>
AuthName WebServerAdmin
AuthType Basic
AuthUserFile /WWWServ/Cfg/AdUser.cfg
<Limit GET POST>
order deny, allow
deny from all
allow from .inetmi.com
require user WWWAdmin
</Limit>
</Directory>
<Directory /*META/ADMIN_MENU>
AuthName WebServerAdmin
AuthType Basic
AuthUserFile /WWWServ/Cfg/AdUser.cfg
<Limit GET POST>
order deny, allow
deny from all
allow from .inetmi.com
require user WWWAdmin
</Limit>
</Directory>
2.18.1.4 Selectively Enabling Administration Mode
Selected areas of administration mode can be made available
to different people if desired. By adding entries to the
administrative access control file, different user names can
have access to different areas on the AS/400. For instance,
if you wanted to give a marketing representative access to
the access log but not access to the configuration files, a
different user name could be created and additional Limits
could be added to the administrative access control
configuration.
Access to dynamic statistics can be granted or denied in
this way as well. By adding a Directory directive that
protects the meta object (section 4.2.12 on page 254)
/*META/STATS, the dynamic statistics can be viewed by more
or fewer people than the rest of the data available through
administration mode.
Page 192
Commerce Server/400 3.0 Commands
3. Commands
Page 193
Commerce Server/400 3.0 Commands
3.1 Web Server Commands
3.1.1 Web Server/400 Commands
There are a number of configuration and operation commands
provided by the Web Server/400 product. They include
commands to work with the server operations (Operational
Commands on page 194), as well as commands to work with, and
modify, the configuration (Configuration Commands on page
194) of the server. Menus (Menus on page 196) are also
provided for convenient access to the product commands.
All of the Web Server/400 command names contain WWW which
stands for World Wide Web.
3.1.1.1 Operational Commands Include:
. STRWWW (section 3.2.1 on page 197) - Start Web Server
. ENDWWW (section 3.2.2 on page 202) - End Web Server
. STRWWWRP (section 3.2.3 on page 204) - Start Web Server
Request Processors
. ENDWWWRP (section 3.2.4 on page 205) - End Web Server
Request Processors
These commands perform the functions to allow operational
use of the server, as well as discontinuing its
availability.
3.1.1.2 Configuration Commands Include:
. CHGWWWCFG (section 3.3.1 on page 207) - Change WWW
Configuration
. SETWWWCFG (section 3.3.2 on page 209) - Set WWW
Configuration Values
. WRKWWWINCL (section 3.3.3 on page 210) - Work with WWW
Include Library
. WRKWWWICON (section 3.3.6 on page 212) - Work with WWW
Index Icons
. WRKWWWSCPL (section 3.3.13 on page 216) - Work with WWW
Script Libraries
Alias Commands:
. WRKWWWALS (section 3.3.16 on page 217) - Work with WWW
Aliases
. ADDWWWALS (section 3.3.17 on page 218) - Add WWW Alias
Entry
Page 194
Commerce Server/400 3.0 Commands
. CHGWWWALS (section 3.3.18 on page 218) - Change WWW
Alias Entry
. DLTWWWALS (section 3.3.19 on page 218) - Delete WWW
Alias Entry
Content Type Commands:
. WRKWWWCTP (section 3.3.20 on page 219) - Work with WWW
Content Types
. ADDWWWCTP (section 3.3.21 on page 220) - Add WWW
Content Type
. CHGWWWCTP (section 3.3.22 on page 220) - Change WWW
Content Type
. DLTWWWCTP (section 3.3.23 on page 220) - Delete WWW
Content Type
Image Map Commands:
. WRKWWWMAP (section 3.3.9 on page 214) - Work with WWW
Image Maps
. ADDWWWMAP (section 3.3.10 on page 215) - Add WWW Image
Map Entry
. CHGWWWMAP (section 3.3.11 on page 215) - Change WWW
Image Map Entry
. DLTWWWMAP (section 3.3.12 on page 215) - Delete WWW
Image Map Entry
User / Authentication Commands:
. WRKWWWUSR (section 3.3.24 on page 221) - Work with WWW
Users
. ADDWWWUSR (section 3.3.25 on page 221) - Add WWW User
Entry
. CHGWWWUSR (section 3.3.26 on page 222) - Change WWW
User Entry
. DLTWWWUSR (section 3.3.27 on page 222) - Delete WWW
User Entry
. MIGWWWUSR (section 3.3.28 on page 222) - Migrate Stream
Users to Database
Directory Based Configuration Commands:
. WRKWWWDIR (section 3.3.29 on page 224) - Work with WWW
Directory Configurations
. WRKWWWLIM (section 3.3.30 on page 225) - Work with WWW
Limits
. CHGWWWDIR (section 3.3.31 on page 226) - Change WWW
Directory
Special Commerce Server/400 Commands:
. CHGWWWSEC (section 3.4.1.1 on page 230) - Change
Commerce Server/400 Configuration
Page 195
Commerce Server/400 3.0 Commands
. CRTWWWKEY (section 3.4.1.2 on page 230) - Create
Commerce Server/400 Keys
. ADDWWWCERT (section 3.4.1.3 on page 234) - Add Commerce
Server/400 Certificate
. CHGWWWKPWD (section 3.4.1.5 on page 236) - Change
Commerce Server/400 Keylist File Password
. ADDWWWROOT (section 3.4.1.4 on page 235) - Add Commerce
Server/400 Root
These commands change the functionality of the server, as
well as default locations for the storage and retrieval of
information, formats for the distribution of document
information, content type and alias transposition
information. The Commerce Server/400 commands are only
available if the Commerce Server/400 product is installed.
3.1.1.3 Authority
Because they are configuration style commands, all Web
Server/400 commands are secured to users who have *ALLOBJ
special authority (e.g., QSECOFR or users with *SECOFR user
class), making it impossible to casually modify the
functionality of the server by unauthorized personnel.
3.1.1.4 Menus
Command menus are also available for convenient access to
the Web Server/400 operational and configuration commands.
The two menus are called CMDWWW and CMDWWWCFG. CMDWWW shows
operational commands and CMDWWWCFG contains the
configuration commands. They can be accessed by typing "GO
MENU(CMDWWW)" or "GO MENU(CMDWWWCFG)" at an AS/400 command
line and pressing the enter key.
Page 196
Commerce Server/400 3.0 Commands
3.2 Operational Commands
3.2.1 STRWWW
3.2.1.1 STRWWW - Start World Wide Web Server
The STRWWW command is used to start the Web Server on the
AS/400. Starting the server allows users to connect to and
receive documents from the AS/400 using Web browsers.
TCP/IP must be started on the AS/400 with the STRTCP command
before the Web Server can be started.
The server jobs (Server Jobs on page 200), advanced
configuration (Advanced Configuration on page 202), and
performance (Server Performance on page 202) topics contain
further information about the server.
3.2.1.2 STRWWW Parameters
CFGFILE - Master Configuration File
Specifies the full-path to the master configuration file
to be used by the server. The master configuration file
(section 5.2.1 on page 336) contains many values that are
used to control how the server starts and runs.
The default master configuration file is
'/WWWServ/Cfg/WebServ.Cfg'. This file can be copied
(e.g., using the CPY command) and changed using the
configuration commands (Configuration Commands on page
194) to create custom master configuration files.
STRWWW sets the PORT (PORT on page 197), RPS (RPS on page
197) and SVRID (SVRID on page 198) parameter values based
on what is configured in the master configuration file
unless the parameters are passed into the command.
For special processing needs, the server can be
configured with multihome processing enabled (section
4.13.9 on page 317).
PORT - Socket Port
The socket port the server is going to process. Refer to
the socket port (section 4.13.18 on page 326)
configuration value for more information.
RPS - Initial Request Processors
The initial number of request processors to start when
the server is started. Refer to the initial request
processors (section 4.11.2 on page 303) configuration
value for more information.
Page 197
Commerce Server/400 3.0 Commands
SVRID - Server Identifier
A unique ID used to identify the server and the server's
jobs. (Server Jobs on page 200) Refer to the server ID
(section 4.13.14 on page 322) configuration value for
more information. The default is to use the configured
value.
If a server ID is not entered or configured, the server
port and host are used to uniquely identify the server
when starting additional request processors (section
3.2.3 on page 204), ending request processors (section
3.2.4 on page 205) and ending the server (section 3.2.2
on page 202); otherwise the entered/configured server ID
is used to uniquely identify the server.
PASSWORD - Password
The current password used to encrypt the server's keylist
file. This parameter is required when running the server
using a secure protocol (i.e., SSL), which requires
Commerce Server/400. The keylist file password was
initially set with the CRTWWWKEY (section 3.4.1.2 on page
230) command. The password can be changed with the
CHGWWWKPWD (section 3.4.1.5 on page 236) command. If the
password is case-sensitive it must be enclosed in single
quotes.
ACTKEY - Product Activation Key
The product activation key is an additional parameter
that is required when starting the server for the first
time. The server will not start until a valid activation
key is provided. The key is no longer required once the
server has successfully started once.
The activation key is provided by your supplier with the
product tape. If the activation key was not sent, does
not work, or your system serial number has changed
contact your supplier.
ENDDATE - Trial Activation Key End Date
The ending date for the trial activation key. The date
must be specified in the job date format.
TCPTIMO - TCP/IP Timeout
The number of minutes to wait for TCP/IP to start. This
parameter is used when TCP/IP has not been completely
started before starting Web Server/400. Web Server/400
will wait up to the specified minutes for TCP/IP to be
started. The default is to wait 10 minutes.
Page 198
Commerce Server/400 3.0 Commands
3.2.1.3 Authority Considerations
1.A user that does not have *ALLOBJ special authority
must be authorized as follows to run the STRWWW
command:
. *USE authority to QSYS/STRWWW *CMD.
. *USE authority to WWWSERVER/WWWDAEPOP *PGM.
. *USE authority to WWWSERVER/WWWDAECPP *PGM.
. *OBJMGT authority to WWWSERVER/WWWDAEMON *PGM.
. *USE authority to QSYS/QSYSNOMAX *JOBQ.
. *READ authority to server configuration files
(section 5.1 on page 333).
. *USE authority to server user profile (section
4.13.17 on page 324).
. *ALL authority to WWWSERVER/WWWACTKEY *DTAARA when
entering a new activation key.
. *ALL authority to an existing server user space.
2.The Server user profile (section 4.13.17 on page 324)
must be authorized as follows to start the server:
. *USE authority to QSYS/QSYSNOMAX *JOBQ.
. *USE authority to all of the libraries in the
library list. The library list of the user starting
the server is used by the server with the exception
of the current library which is always set to
library WWWSERVER.
. Create authority to the configured log
libraries/directories. At least execute authority to
the preceding directories when logging to IFS.
. *RX authority to the configured keylist file.
Commerce Server/400 requirement when running a
secure server.
3.The system value QALWUSRDMN must be set to allow user-
domain objects to be created in libraries QTEMP and
WWWSERVER.
4.A user must meet one of the following conditions to
modify or end the started server:
. User that started the server
. User with *ALLOBJ authority
. User that has been granted *ALL authority to the
server user space. The authority must be granted
after starting the server. The server user space can
be found in the WWWSERVER product library and it is
named as follows: WWU appended with the server
identifer (SVRID on page 198).
3.2.1.4 Server does not Start
If the server does not start consult the following for more
information:
1.Display the joblog (e.g., DSPJOBLOG)
Page 199
Commerce Server/400 3.0 Commands
2.Work with and display the server user profile (section
4.13.17 on page 324) spooled files (e.g., WRKSPLF
SELECT(WWWUSER)).
Correct the problem and try to start the server again.
3.2.1.5 Server Jobs
When performing a WRKACTJOB command after starting the Web
Server with multihome (section 4.13.9 on page 317) disabled
using the default server ID (SVRID on page 198) the server
jobs can be identified as follows:
Subsystem/Job User Type CPU % Function
Status
QSYSWRK QSYS SBS .0
DEQW
WWD80 WWWUSER BCH .0 PGM-WWWDAEMON
TIMW
WWL80 WWWUSER BCH .0 PGM-WWWDLOG
DEQW
WWR80 WWWUSER BCH .0 PGM-WWWDRP
DEQW
WWR80 WWWUSER BCH .0 PGM-WWWDRP
DEQW
When multihome (section 4.13.9 on page 317) is enabled using
configured server IDs (SVRID on page 198) the server jobs
can be identified as follows:
Subsystem/Job User Type CPU % Function
Status
QSYSWRK QSYS SBS .0
DEQW
WWDINET WWWUSER BCH .0 PGM-WWWDAEMON
TIMW
WWDKAZOO WWWUSER BCH .0 PGM-WWWDAEMON
SELW
WWLINET WWWUSER BCH .0 PGM-WWWDLOG
DEQW
WWLKAZOO WWWUSER BCH .0 PGM-WWWDLOG
DEQW
WWRINET WWWUSER BCH .0 PGM-WWWDRP
DEQW
WWRKAZOO WWWUSER BCH .0 PGM-WWWDRP
DEQW
WWRKAZOO WWWUSER BCH .0 PGM-WWWDRP
DEQW
where,
WWWUSER
is the default server user profile. All server jobs run
under the configured server user profile (section 4.13.17
on page 324). WWWUSER's profile is setup to use the
Page 200
Commerce Server/400 3.0 Commands
WWWSERVER/WWWJOBD job description, which is configured to
use the QSYS/QSYSNOMAX job queue.
QSYSWRK
is the subsystem where the server jobs are running. The
QSYSNOMAX job queue is configured to run multiple active
jobs in the QSYSWRK subsystem.
WWDxx
is the server. One server job exists to handle requests
for a single host and port. The server job accepts the
request and immediately passes it on to a request
processor.
The name of the server job is WWD appended with the
server identifier (SVRID on page 198). In the first set
of jobs a single server is running with the default
server ID of '80', which is the port the server is
processing. The second set of jobs show two servers
running with configured server IDs: 'INET' and 'KAZOO'.
The host and port(s) the server is processing can be
displayed by performing the following command:
DSPOBJD OBJ(WWWSERVER/WWQxx) OBJTYPE(*USRQ) DETAIL(*FULL)
where the name of the user queue is the same as the
server job name except for the D is replaced with a Q.
The displayed user queue text contains the port(s) and
host that the server is processing. For example,
Text . . . . : PORT: 80 HOST: www.inetmi.com
Text . . . . : PORT: 80/443 HOST: www.inetmi.com
indicates the server is processing host 'www.inetmi.com'
on port 80. The second example is running the Commerce
Server/400; HTTP protocol is being processed on port 80
and SSL is being processed on port 443.
WWLxx
is the log server. The log server is used to write out
the server access and error logs. One log server job
exists to handle requests for a single host and port. The
xx characters represent the server ID (SVRID on page
198).
WWRxx
are the server request processors. Each host and port can
have many request processors. Each request is handled to
completion by a single request processor. The xx
characters represent the server ID (SVRID on page 198).
Page 201
Commerce Server/400 3.0 Commands
3.2.1.6 Advanced Configuration
Server Jobs
The server user profile (section 4.13.17 on page 324)
(e.g., WWWUSER) configuration controls how the server
jobs are run. All of the attributes for the server jobs
are retrieved from the server user profile and the
profile's configured job description. The server user
profile's job description defines the job queue that is
used to submit the server jobs. The configured job queue
must support multiple active jobs (e.g., QSYSNOMAX).
Also, the job description's routing data (e.g., RUNPTY20)
must be setup appropriately for the job queue and
subsystem that is being used. The ability to change the
server user profile and job description gives you the
ability to configure how you want the server to run on
your system.
Library List
The user part of the library list for the server jobs can
be controlled with the Initial Library List (section
4.13.8 on page 316) configuration value.
3.2.1.7 Server Performance
The server performance is affected by many factors:
. AS/400 relative performance rating
. Percentage of system auxiliary storage used
. Amount of memory (main storage) installed
. Pool configuration
. Number of jobs running on the system (i.e., system
load)
. Network speed
Improving any of the factors above can lead to increased
server throughput.
By default, TCP/IP, Client Access/400 and Web Server/400
jobs run in the *BASE pool (i.e., system pool 2). Server
performance can be improved by reducing the number of page
faults in the *BASE pool by adjusting the pool sizes. Also,
advanced configuration (Advanced Configuration on page 202)
provides information that can be used to customize how the
server runs on your system.
3.2.2 ENDWWW
3.2.2.1 ENDWWW - End World Wide Web Server
The ENDWWW command is used to end one or more running Web
Servers. The server(s) can be identified using either the
PORT (PORT on page 203) and HOST (HOST on page 203)
parameters or the SVRID (SVRID on page 203) parameter. Care
Page 202
Commerce Server/400 3.0 Commands
must be taken when ending Web Servers to ensure the correct
server(s) are being ended.
The ENDWWW command returns before all of the server jobs
have ended. The WRKACTJOB command can be used to identify
when all of the server jobs have been ended.
3.2.2.2 ENDWWW Parameters
PORT - Socket Port
Identifies the server to end by the socket port the
server is processing. The port and host (HOST on page
203) uniquely identify the server ending. Refer to the
socket port (section 4.13.18 on page 326) configuration
value for more information.
The special value *ALL may be used to end all running
servers.
This parameter is only used when the server ID (SVRID on
page 203) parameter is set to *PORT.
HOST - Host Name or IP Address
Identifies the host the server is processing. The default
value is *NOMULTIHOME. The default value must be used if
the server has multihome processing (section 4.13.9 on
page 317) disabled. A valid host must be specified if the
server has multihome processing enabled. The host can be
identified with either a host name or an IP address. If
the host is not known then the server jobs (Server Jobs
on page 200) can be used to determine the host name.
The special value *ALL may be used to end all running
servers on a specified port.
This parameter is only used when the server ID (SVRID on
page 203) parameter is set to *PORT.
SVRID - Server Identifier
Used to identify a specific server to be ended. The
server identifier is assigned to the server at startup
(SVRID on page 198). The server ID entered can be either
a configured (section 4.13.14 on page 322) or default
(section 4.13.14 on page 322) value.
This parameter must be used to end a specific server if
the server identifier is not the default server ID. The
default of *PORT indicates that the PORT and HOST
parameters are to be used to identify the server(s) to
end.
Page 203
Commerce Server/400 3.0 Commands
3.2.2.3 Authorizing a User to ENDWWW
A user that does not have *ALLOBJ special authority must be
authorized as follows to run the ENDWWW command:
. *USE authority to QSYS/ENDWWW *CMD
. *USE authority to WWWSERVER/WWWDAEMON *PGM
. *ALL authority to the server user space (server user
space on page 199)
3.2.3 STRWWWRP
3.2.3.1 STRWWWRP - Start World Wide Web Server Request
Processors
The STRWWWRP command is used to start additional Web Server
request processors for a specific server. The server can be
identified using either the PORT (PORT on page 204) and HOST
(HOST on page 204) parameters or the SVRID (SVRID on page
205) parameter. The SVRID (SVRID on page 205) parameter must
be used to identify the server if a server identifier was
specified when starting the server (SVRID on page 198).
Starting additional request processors allows the server to
handle more concurrent requests. The initial number of
request processors are started when the server is started
using the STRWWW (section 3.2.1 on page 197) command.
Additional request processors will also start dynamically
based on the request wait timeout (section 4.11.4 on page
305) configuration value.
3.2.3.2 STRWWWRP Parameters
PORT - Socket Port
The socket port to start additional server request
processors on. The default value is 80. The port and host
(HOST on page 204) uniquely identify the running server.
Refer to the socket port (section 4.13.18 on page 326)
configuration value for more information.
This parameter is only used when the server ID (SVRID on
page 205) parameter is set to *PORT.
RPS - Additional Request Processors
The number of additional server request processors to
start. The default value is 1. The maximum request
processors (section 4.11.3 on page 304) configuration
value determines the total number of request processors
that can be started.
HOST - Host Name or IP Address
Identifies the host the server is processing. The default
value is *NOMULTIHOME. The default value must be used if
the server has multihome processing (section 4.13.9 on
page 317) disabled. A valid host must be specified if the
Page 204
Commerce Server/400 3.0 Commands
server has multihome processing enabled. The host can be
identified with either a host name or an IP address. If
the host is not known then the server jobs (Server Jobs
on page 200) can be used to determine the host name.
This parameter is only used when the server ID (SVRID on
page 205) parameter is set to *PORT.
SVRID - Server Identifier
Used to identify the server for which request processors
are to be started. The server identifier is assigned to
the server at startup (SVRID on page 198). The server ID
entered can be either a configured (section 4.13.14 on
page 322) or default (section 4.13.14 on page 322) value.
This parameter must be used if the server identifier is
not the default server ID. The default of *PORT indicates
that the PORT and HOST parameters are to be used to
identify the server.
3.2.3.3 Authorizing a User to STRWWWRP
A user that does not have *ALLOBJ special authority must be
authorized as follows to run the STRWWWRP command:
. *USE authority to QSYS/STRWWWRP *CMD
. *USE authority to WWWSERVER/WWWDAEMON *PGM
. *USE authority to QSYS/QSYSNOMAX *JOBQ
. *USE authority to server user profile (section 4.13.17
on page 324)
. *ALL authority to the server user space (server user
space on page 199)
3.2.4 ENDWWWRP
3.2.4.1 ENDWWWRP - End World Wide Web Server Request
Processors
The ENDWWWRP command is used to end Web Server request
processors for a specific server that are no longer needed.
The server can be identified using either the PORT (PORT on
page 206) and HOST (HOST on page 206) parameters or the
SVRID (SVRID on page 206) parameter. The SVRID (SVRID on
page 206) parameter must be used to identify the server if a
server identifier was specified when starting the server
(SVRID on page 198).
The initial number of request processors are started when
the server is started using the STRWWW (section 3.2.1 on
page 197) command. Additional request processors could have
been started with the STRWWWRP (section 3.2.3 on page 204)
command or started dynamically based on the request wait
timeout (section 4.11.4 on page 305) configuration value.
Page 205
Commerce Server/400 3.0 Commands
3.2.4.2 ENDWWWRP Parameters
PORT - Socket Port
The socket port to end server request processors on. The
default value is 80. The port and host (HOST on page 206)
uniquely identify the running server. Refer to the socket
port (section 4.13.18 on page 326) configuration value
for more information.
This parameter is only used when the server ID (SVRID on
page 206) parameter is set to *PORT.
RPS - Request Processors to End
The number of server request processors to end. The
default value is 1. The value must be less than the
currently number of running request processors. To end
all request processors and the server use the ENDWWW
(section 3.2.2 on page 202) command.
HOST - Host Name or IP Address
Identifies the host the server is processing. The default
value is *NOMULTIHOME. The default value must be used if
the server has multihome processing (section 4.13.9 on
page 317) disabled. A valid host must be specified if the
server has multihome processing enabled. The host can be
identified with either a host name or an IP address. If
the host is not known then the server jobs (Server Jobs
on page 200) can be used to determine the host name.
This parameter is only used when the server ID (SVRID on
page 206) parameter is set to *PORT.
SVRID - Server Identifier
Used to identify the server for which request processors
are to be ended. The server identifier is assigned to the
server at startup (SVRID on page 198). The server ID
entered can be either a configured (section 4.13.14 on
page 322) or default (section 4.13.14 on page 322) value.
This parameter must be used if the server identifier is
not the default server ID. The default of *PORT indicates
that the PORT and HOST parameters are to be used to
identify the server.
3.2.4.3 Authorizing a User to ENDWWWRP
A user that does not have *ALLOBJ special authority must be
authorized as follows to run the ENDWWWRP command:
. *USE authority to QSYS/ENDWWWRP *CMD
. *USE authority to WWWSERVER/WWWDAEMON *PGM
. *ALL authority to the server user space (server user
space on page 199)
Page 206
Commerce Server/400 3.0 Commands
3.3 Configuration Commands
3.3.1 CHGWWWCFG
3.3.1.1 CHGWWWCFG - Change WWW Configuration
This is the primary configuration command for the Web
Server/400. The parameters in this command allow you to
configure the functionality of the server, including how
many request processors (RPs) will be allowed to run at any
one time, a timeout variable to ensure that each request
returns in a reasonable amount of time (even if that
includes a message indicating no data returned), variables
for how information (and how much information) is presented
to the user for the files and directories returned, and
variables for index styles and system icon locations. Other
parameters determine the default locations of the error log
file, the access log file, document root directory, server
root directory, the public user's home directory, image map
configuration file, and others.
The parameters associated with the CHGWWWCFG command are:
. CFGFILE - Master Configuration File (section 5.2.1 on
page 336)
. ACCGBLFILE - Directory based configuration file path
(section 5.4.1 on page 343)
. ACCADMFILE - Administrator access file path (section
5.4.2 on page 344)
. ALIASFILE - Alias file path (section 4.3.2 on page 262)
. CONTENT - Content type file path (section 4.5.2 on page
270)
. DEFCONTYPE - Default content type (section 4.6.1 on
page 271)
. DOCROOT - Document root path (section 4.6.2 on page
271)
. DOCROOTQ - Document root for QDLS (section 4.6.3 on
page 272)
. DOCROOTSYS - Document root for QSYS (section 4.6.4 on
page 273)
. SVRROOT - Server root path (section 4.6.5 on page 274)
. SYSICONS - System icon paths (section 4.6.6 on page
275)
. IDXDFTVIEW - Index default view (section 4.7.2 on page
278)
. EXCLUDEIDX - Exclude index files (section 4.7.3 on page
279)
. IDXFOTFILE - Index footer file (section 4.7.4 on page
280)
. IDXHEDFILE - Index header file (section 4.7.5 on page
281)
Page 207
Commerce Server/400 3.0 Commands
. IDXSTYLE - Index style (section 4.7.7 on page 284)
. SENDDIRLEN - Send directory content length (section
4.7.8 on page 285)
. IMGMAPFILE - Image map file path (section 4.8.4 on page
289)
. ACCLOGFILE - Access log file path (section 4.10.2 on
page 294)
. ACCCYCLE - Access log cycle (section 4.10.1 on page
293)
. ERRLOGFILE - Error log file path (section 4.10.4 on
page 297)
. ERRCYCLE - Error log cycle (section 4.10.3 on page 295)
. ERRLOGLVL - Error logging level (section 4.10.5 on page
298)
. STTLOGFILE - Statistics log file path (section 4.10.7
on page 300)
. STTCYCLE - Statistics log cycle (section 4.10.6 on page
299)
. STTRAWDATA - Statistics raw data (section 4.10.8 on
page 301)
. CONNQUESIZ - Connection queue size (section 4.11.1 on
page 303)
. INITRPS - Initial request processors (section 4.11.2 on
page 303)
. MAXRPS - Maximum request processors (section 4.11.3 on
page 304)
. TIMEOUT - Request wait timeout (section 4.11.5 on page
306)
. THRESHOLD - Wait threshold (section 4.11.4 on page 305)
. ENABLESCPT - Enable scripts (section 4.12.1 on page
308)
. CNTNTCCSID - Content CCSID (section 4.13.2 on page 311)
. DEFSRCTYPE - Default source type (section 4.13.3 on
page 311)
. DISABLESVR - Disable server (section 4.13.4 on page
312)
. DOMNAMLOOK - Domain name lookup (section 4.13.5 on page
313)
. IDXNAME - Index name (section 4.13.7 on page 315)
. SENDFILLEN - Send file content length (section 4.13.10
on page 319)
. SENDMOD