[0001]
[0002]
[0003]
[0004]
[0005]
[0006]
[0007]
[0008]
[0009]
[0010]
[0011]
[0012]
[0013]
[0014]
[0015]
[0016]
[0017]
[0018]
[0019]
[0020]
[0021]
[0022]
[0023]
[0024]
[0025]
[0026]
[0027]
[0028]
[0029]
[0030]
[0031]
[0032]
[0033]
[0034]
[0035]
[0036]
[0037]
[0038]
[0039]
[0040]
[0041]
[0042]
[0043]
[0044]
[0045]
[0046]
[0047]
[0048]
[0049]
[0050]
[0051]
[0052]
[0053]
[0054]
[0055]
[0056]
[0057]
[0058]
[0059]
[0060]
[0061]
[0062]
[0063]
[0064]
[0065]
[0066]
[0067]
[0068]
[0069]
[0070]
[0071]
[0072]
[0073]
[0074]
[0075]
[0076]
[0077]
[0078]
[0079]
[0080]
[0081]
[0082]
[0083]
[0084]
[0085]
[0086]
[0087]
[0088]
[0089]
[0090]
[0091]
[0092]
[0093]
[0094]
[0095]
[0096]
[0097]
[0098]
[0099]
[0100]
[0101]
[0102]
[0103]
[0104]
[0105]
[0106]
[0107]
[0108]
[0109]
[0110]
[0111]
[0112]
[0113]
[0114]
[0115]
[0116]
[0117]
[0118]
[0119]
[0120]
[0121]
[0122]
[0123]
[0124]
[0125]
[0126]
[0127]
[0128]
[0129]
[0130]
[0131]
[0132]
[0133]
[0134]
[0135]
[0136]
[0137]
[0138]
[0139]
[0140]
[0141]
[0142]
[0143]
[0144]
[0145]
[0146]
[0147]
[0148]
[0149]
[0150]
[0151]
[0152]
[0153]
[0154]
[0155]
[0156]
[0157]
[0158]
[0159]
[0160]
[0161]
[0162]
[0163]
[0164]
[0165]
[0166]
[0167]
[0168]
[0169]
[0170]
[0171]
[0172]
[0173]
[0174]
[0175]
[0176]
[0177]
[0178]
[0179]
[0180]
[0181]
[0182]
[0183]
[0184]
[0185]
[0186]
[0187]
[0188]
[0189]
[0190]
[0191]
[0192]
[0193]
[0194]
[0195]
[0196]
[0197]
[0198]
[0199]
[0200]
[0201]
[0202]
[0203]
[0204]
[0205]
[0206]
[0207]
[0208]
[0209]
[0210]
[0211]
[0212]
[0213]
[0214]
[0215]
[0216]
[0217]
[0218]
[0219]
[0220]
[0221]
[0222]
[0223]
[0224]
[0225]
[0226]
[0227]
[0228]
[0229]
[0230]
[0231]
[0232]
[0233]
[0234]
[0235]
[0236]
[0237]
[0238]
[0239]
[0240]
[0241]
[0242]
[0243]
[0244]
[0245]
[0246]
[0247]
[0248]
[0249]
[0250]
[0251]
[0252]
[0253]
[0254]
[0255]
[0256]
[0257]
[0258]
[0259]
[0260]
[0261]
[0262]
[0263]
[0264]
[0265]
[0266]
[0267]
[0268]
[0269]
[0270]
[0271]
[0272]
[0273]
[0274]
[0275]
[0276]
[0277]
[0278]
[0279]
[0280]
[0281]
[0282]
[0283]
[0284]
[0285]
[0286]
[0287]
[0288]
[0289]
[0290]
[0291]
[0292]
[0293]
[0294]
[0295]
[0296]
[0297]
[0298]
[0299]
[0300]
[0301]
[0302]
[0303]
[0304]
[0305]
[0306]
[0307]
[0308]
[0309]
[0310]
[0311]
[0312]
[0313]
[0314]
[0315]
[0316]
[0317]
[0318]
[0319]
[0320]
[0321]
[0322]
[0323]
[0324]
[0325]
[0326]
[0327]
[0328]
[0329]
[0330]
[0331]
[0332]
[0333]
[0334]
[0335]
[0336]
[0337]
[0338]
[0339]
[0340]
[0341]
[0342]
[0343]
[0344]
[0345]
[0346]
[0347]
[0348]
[0349]
[0350]
[0351]
[0352]
[0353]
[0354]
[0355]
[0356]
[0357]
[0358]
[0359]
[0360]
[0361]
[0362]
[0363]
[0364]
[0365]
[0366]
[0367]
[0368]
[0369]
[0370]
[0371]
[0372]
[0373]
[0374]
[0375]
[0376]
[0377]
[0378]
[0379]
[0380]
[0381]
[0382]
[0383]
[0384]
[0385]
[0386]
[0387]
[0388]
[0389]
[0390]
[0391]
[0392]
[0393]
[0394]
[0395]
[0396]
[0397]
[0398]
[0399]
[0400]
[0401]
[0402]
[0403]
[0404]
[0405]
[0406]
[0407]
[0408]
[0409]
[0410]
[0411]
[0412]
[0413]
[0414]
[0415]
[0416]
[0417]
[0418]
[0419]
[0420]
[0421]
[0422]
[0423]
[0424]
[0425]
[0426]
[0427]
[0428]
[0429]
[0430]
[0431]
[0432]
[0433]
[0434]
[0435]
[0436]
[0437]
[0438]
[0439]
[0440]
[0441]
[0442]
[0443]
[0444]
[0445]
[0446]
[0447]
[0448]
[0449]
[0450]
[0451]
[0452]
[0453]
[0454]
[0455]
[0456]
[0457]
[0458]
[0459]
[0460]
[0461]
[0462]
[0463]
[0464]
[0465]
[0466]
[0467]
[0468]
[0469]
[0470]
[0471]
[0472]
[0473]
[0474]
[0475]
[0476]
[0477]
[0478]
[0479]
[0480]
[0481]
[0482]
[0483]
[0484]
[0485]
[0486]
[0487]
[0488]
[0489]
[0490]
[0491]
[0492]
[0493]
[0494]
[0495]
[0496]
[0497]
[0498]
[0499]
[0500]
[0501]
[0502]
[0503]
[0504]
[0505]
[0506]
[0507]
[0508]
[0509]
[0510]
[0511]
[0512]
[0513]
[0514]
[0515]
[0516]
[0517]
[0518]
[0519]
[0520]
[0521]
[0522]
[0523]
[0524]
[0525]
[0526]
[0527]
[0528]
[0529]
[0530]
[0531]
[0532]
[0533]
[0534]
[0535]
[0536]
[0537]
[0538]
[0539]
[0540]
[0541]
[0542]
[0543]
[0544]
[0545]
[0546]
[0547]
[0548]
[0549]
[0550]
[0551]
[0552]
[0553]
[0554]
[0555]
[0556]
[0557]
[0558]
[0559]
[0560]
[0561]
[0562]
[0563]
[0564]
[0565]
[0566]
[0567]
[0568]
[0569]
[0570]
[0571]
[0572]
[0573]
[0574]
[0575]
[0576]
[0577]
[0578]
[0579]
[0580]
[0581]
[0582]
[0583]
[0584]
[0585]
[0586]
[0587]
[0588]
[0589]
[0590]
[0591]
[0592]
[0593]
[0594]
[0595]
[0596]
[0597]
[0598]
[0599]
[0600]
[0601]
[0602]
[0603]
[0604]
[0605]
[0606]
[0607]
[0608]
[0609]
[0610]
[0611]
[0612]
[0613]
[0614]
[0615]
[0616]
[0617]
[0618]
[0619]
[0620]
[0621]
[0622]
[0623]
[0624]
[0625]
[0626]
[0627]
[0628]
[0629]
[0630]
[0631]
[0632]
[0633]
[0634]
[0635]
[0636]
[0637]
[0638]
[0639]
[0640]
[0641]
[0642]
[0643]
[0644]
[0645]
[0646]
[0647]
[0648]
[0649]
[0650]
[0651]
[0652]
[0653]
[0654]
[0655]
[0656]
[0657]
[0658]
[0659]
[0660]
[0661]
[0662]
[0663]
[0664]
[0665]
[0666]
[0667]
[0668]
[0669]
[0670]
[0671]
[0672]
[0673]
[0674]
[0675]
[0676]
[0677]
[0678]
[0679]
[0680]
[0681]
[0682]
[0683]
[0684]
[0685]
[0686]
[0687]
[0688]
[0689]
[0690]
[0691]
[0692]
[0693]
[0694]
[0695]
[0696]
[0697]
[0698]
[0699]
[0700]
[0701]
[0702]
[0703]
[0704]
[0705]
[0706]
[0707]
[0708]
[0709]
[0710]
[0711]
[0712]
[0713]
[0714]
[0715]
[0716]
[0717]
[0718]
[0719]
[0720]
[0721]
[0722]
[0723]
[0724]
[0725]
[0726]
[0727]
[0728]
[0729]
[0730]
[0731]
[0732]
[0733]
[0734]
[0735]
[0736]
[0737]
[0738]
[0739]
[0740]
[0741]
[0742]
[0743]
[0744]
[0745]
[0746]
[0747]
[0748]
[0749]
[0750]
[0751]
[0752]
[0753]
[0754]
[0755]
[0756]
[0757]
[0758]
[0759]
[0760]
[0761]
[0762]
[0763]
[0764]
[0765]
[0766]
[0767]
[0768]
[0769]
[0770]
[0771]
[0772]
[0773]
[0774]
[0775]
[0776]
[0777]
[0778]
[0779]
[0780]
[0781]
[0782]
[0783]
[0784]
[0785]
[0786]
[0787]
[0788]
[0789]
[0790]
[0791]
[0792]
[0793]
[0794]
[0795]
[0796]
[0797]
[0798]
[0799]
[0800]
[0801]
[0802]
[0803]
[0804]
[0805]
[0806]
[0807]
[0808]
[0809]
[0810]
[0811]
[0812]
[0813]
[0814]
[0815]
[0816]
[0817]
[0818]
[0819]
[0820]
[0821]
[0822]
[0823]
[0824]
[0825]
[0826]
[0827]
[0828]
[0829]
[0830]
[0831]
[0832]
[0833]
[0834]
[0835]
[0836]
[0837]
[0838]
[0839]
[0840]
[0841]
[0842]
[0843]
[0844]
[0845]
[0846]
[0847]
[0848]
[0849]
[0850]
[0851]
[0852]
[0853]
[0854]
[0855]
[0856]
[0857]
[0858]
[0859]
[0860]
[0861]
[0862]
[0863]
[0864]
[0865]
[0866]
[0867]
[0868]
[0869]
[0870]
[0871]
[0872]
[0873]
[0874]
[0875]
[0876]
[0877]
[0878]
[0879]
[0880]
[0881]
[0882]
[0883]
[0884]
[0885]
[0886]
[0887]
[0888]
[0889]
[0890]
[0891]
[0892]
[0893]
[0894]
[0895]
[0896]
[0897]
[0898]
[0899]
[0900]
[0901]
[0902]
[0903]
[0904]
[0905]
[0906]
[0907]
[0908]
[0909]
[0910]
[0911]
[0912]
[0913]
[0914]
[0915]
[0916]
[0917]
[0918]
[0919]
[0920]
[0921]
[0922]
[0923]
[0924]
[0925]
[0926]
[0927]
[0928]
[0929]
[0930]
[0931]
[0932]
[0933]
[0934]
[0935]
[0936]
[0937]
[0938]
[0939]
[0940]
[0941]
[0942]
[0943]
[0944]
[0945]
[0946]
[0947]
[0948]
[0949]
[0950]
[0951]
[0952]
[0953]
[0954]
[0955]
[0956]
[0957]
[0958]
[0959]
[0960]
[0961]
[0962]
[0963]
[0964]
[0965]
[0966]
[0967]
[0968]
[0969]
[0970]
[0971]
[0972]
[0973]
[0974]
[0975]
[0976]
[0977]
[0978]
[0979]
[0980]
[0981]
[0982]
[0983]
[0984]
[0985]
[0986]
[0987]
[0988]
[0989]
[0990]
[0991]
[0992]
[0993]
[0994]
[0995]
[0996]
[0997]
[0998]
[0999]
[1000]
[1001]
[1002]
[1003]
[1004]
[1005]
[1006]
[1007]
[1008]
[1009]
[1010]
[1011]
[1012]
[1013]
[1014]
[1015]
[1016]
[1017]
[1018]
[1019]
[1020]
[1021]
[1022]
[1023]
[1024]
[1025]
[1026]
[1027]
[1028]
[1029]
[1030]
[1031]
[1032]
[1033]
[1034]
[1035]
[1036]
[1037]
[1038]
[1039]
[1040]
[1041]
[1042]
[1043]
[1044]
[1045]
[1046]
[1047]
[1048]
[1049]
[1050]
[1051]
[1052]
[1053]
[1054]
[1055]
[1056]
[1057]
[1058]
[1059]
[1060]
[1061]
[1062]
[1063]
[1064]
[1065]
[1066]
[1067]
[1068]
[1069]
[1070]
[1071]
[1072]
[1073]
[1074]
[1075]
[1076]
[1077]
[1078]
[1079]
[1080]
[1081]
[1082]
[1083]
[1084]
[1085]
[1086]
[1087]
[1088]
[1089]
[1090]
[1091]
[1092]
[1093]
[1094]
[1095]
[1096]
[1097]
[1098]
[1099]
[1100]
[1101]
[1102]
[1103]
[1104]
[1105]
[1106]
[1107]
[1108]
[1109]
[1110]
[1111]
[1112]
[1113]
[1114]
[1115]
[1116]
[1117]
[1118]
[1119]
[1120]
[1121]
[1122]
[1123]
[1124]
[1125]
[1126]
[1127]
[1128]
[1129]
[1130]
[1131]
[1132]
[1133]
[1134]
[1135]
[1136]
[1137]
[1138]
[1139]
[1140]
[1141]
[1142]
[1143]
[1144]
[1145]
[1146]
[1147]
[1148]
[1149]
[1150]
[1151]
[1152]
[1153]
[1154]
[1155]
[1156]
[1157]
[1158]
[1159]
[1160]
[1161]
[1162]
[1163]
[1164]
[1165]
[1166]
[1167]
[1168]
[1169]
[1170]
[1171]
[1172]
[1173]
[1174]
[1175]
[1176]
[1177]
[1178]
[1179]
[1180]
[1181]
[1182]
[1183]
[1184]
[1185]
[1186]
[1187]
[1188]
[1189]
[1190]
[1191]
[1192]
[1193]
[1194]
[1195]
[1196]
[1197]
[1198]
[1199]
[1200]
[1201]
[1202]
[1203]
[1204]
[1205]
[1206]
[1207]
[1208]
[1209]
[1210]
[1211]
[1212]
[1213]
[1214]
[1215]
[1216]
[1217]
[1218]
[1219]
[1220]
[1221]
[1222]
[1223]
[1224]
[1225]
[1226]
[1227]
[1228]
[1229]
[1230]
[1231]
[1232]
[1233]
[1234]
[1235]
[1236]
[1237]
[1238]
[1239]
[1240]
[1241]
[1242]
[1243]
[1244]
[1245]
[1246]
[1247]
[1248]
[1249]
[1250]
[1251]
[1252]
[1253]
[1254]
[1255]
[1256]
[1257]
[1258]
[1259]
[1260]
[1261]
[1262]
[1263]
[1264]
[1265]
[1266]
[1267]
[1268]
[1269]
[1270]
[1271]
[1272]
[1273]
[1274]
[1275]
[1276]
[1277]
[1278]
[1279]
[1280]
[1281]
[1282]
[1283]
[1284]
[1285]
[1286]
[1287]
[1288]
[1289]
[1290]
[1291]
[1292]
[1293]
[1294]
[1295]
[1296]
[1297]
[1298]
[1299]
[1300]
[1301]
[1302]
[1303]
[1304]
[1305]
[1306]
[1307]
[1308]
[1309]
[1310]
[1311]
[1312]
[1313]
[1314]
[1315]
[1316]
[1317]
[1318]
[1319]
[1320]
[1321]
[1322]
[1323]
[1324]
[1325]
[1326]
[1327]
[1328]
[1329]
[1330]
[1331]
[1332]
[1333]
[1334]
[1335]
[1336]
[1337]
[1338]
[1339]
[1340]
[1341]
[1342]
[1343]
[1344]
[1345]
[1346]
[1347]
[1348]
[1349]
[1350]
[1351]
[1352]
[1353]
[1354]
[1355]
[1356]
[1357]
[1358]
[1359]
[1360]
[1361]
[1362]
[1363]
[1364]
[1365]
[1366]
[1367]
[1368]
[1369]
[1370]
[1371]
[1372]
[1373]
[1374]
[1375]
[1376]
[1377]
[1378]
[1379]
[1380]
[1381]
[1382]
[1383]
[1384]
[1385]
[1386]
[1387]
[1388]
[1389]
[1390]
[1391]
[1392]
[1393]
[1394]
[1395]
[1396]
[1397]
[1398]
[1399]
[1400]
[1401]
[1402]
[1403]
[1404]
[1405]
[1406]
[1407]
[1408]
<!DOCTYPE html>
<!-- WASDOC AXP-2.0.0 (CGILIB AXP-1.9.9) -->
<!-- wasDOC Copyright (C) 2019,2020 Mark G.Daniel - Apache-2.0 licenced -->
<!--  3-NOV-2021 02:50 -->
<noscript>NOTE: SOME FUNCTIONALITY EMPLOYS JAVASCRIPT</noscript>
<div id="erreport1" style="display:none;"></div>
<script>
function errorReport(string) {
   for (var cnt = 1; cnt <= 2; cnt++) {
      var err = document.getElementById('erreport'+cnt);
      err.style.display = 'block';
      err.innerHTML += string;
   }
}
</script>
<style type="text/css">
html { font-family: arial, verdana, sans-serif; font-size:12pt; margin:1em; }
h1 { font-size:124%; font-style:bold;
     margin-top:1em; margin-bottom:0.5em; }
h2 { font-size:120%; font-style:bold;
     margin-top:1.1em; margin-bottom:0.4em; }
h3 { font-size:116%; font-style:bold;
     margin-top:1.0em; margin-bottom:0.3em; }
h4 { font-size:112%; font-style:bold;
     margin-top:1.1em; margin-bottom:0.3em; }
h5 { font-size:112%; font-style:bold; 
     margin-top:1.1em; margin-bottom:0.3em; }
h6 { font-size:112%; font-style:bold; padding:0; margin:0; }

h1 .text { text-decoration:underline; }
h1 .numb { padding-right:0.8em; }
h1 .numb:empty { display:none; padding-right:0; }
h2 .numb { padding-right:0.8em; }
h2 .numb:empty { display:none; padding-right:0; }
h3 .numb { padding-right:0.8em; }
h3 .numb:empty { display:none; padding-right:0; }
h4 .numb { padding-right:0.8em; }
h4 .numb:empty { display:none; padding-right:0; }
h5 .numb { display:none; padding-right:0; }
h6 .numb { display:none; padding-right:0; }

kbd { font-family:monospace; }

noscript { font-size:1.2em; }

p { line-height:1.1em; margin-top:1em; margin-bottom:1em; }

.chunk { font-size:130%; text-decoration:underline; }
.head {}
.high {}
.bold { font-weight:bold; }
.center { text-align:center; }
.italic { font-style:italic; }
.left { text-align:left; }
.nowrap { white-space:nowrap; }
.prewrap { white-space:pre; }
.right { text-align:right; }
.strike { text-decoration:line-through; }
.under { text-decoration:underline; }

.backlight { background-color:#f2f2f2; }
.display0 { display:none; }

img { max-width:100%; }
.imglink { }

.link { }
.blank { }

.list { margin-bottom:1em; }
.list li { margin-top:0.5em; }
.list0 li { margin-top:0; }
.item {}

.tabl { border-collapse:collapse; text-align:left; margin:0.4em 2em 0.5em 2em; }
.tabu { border-collapse:collapse; text-align:right; margin:0.4em 2em 0.5em 2em; }

.tabr { vertical-align:top; }
.tabh { padding:0.2em 0 0 2em; margin:0; }
.tabd { padding:0.1em 0 0 2em; margin:0; }
.tabh:first-of-type, td:first-of-type { padding-left:0; }

.tabu .tabh,
.tabu .tabd { border:1px solid gray; padding:0.2em 0.3em 0.2em 0.3em; }
.tab0 { border:none; visibility:hidden; max-width:1em; 
        white-space:nowrap; overflow:hidden; }

.tabauto { margin-left:auto; margin-right:auto; }

.tabr:empty { height:0.2em; }
.tabu .tabh:empty, .tabu .tabd:empty { border:none; visibility:hidden; }

.error { font-size:110%; color:black; background-color:yellow;
         font-family:sans-serif; font-weight:bold; font-style:normal;
         width:95%; border:solid 1px gray; padding:0.5em 1em 0.5em 1em; }
.error::before { content:'\026a0\00a0'; }
.image { }
.page { width:98%; border:1px dashed gray; margin:1.5em 0 1.8em 0; }
.epage { width:98%; border:1px dashed black; margin:1.5em 0 1.8em 0; }
.monosp { font-family:monospace; }
.ppage { display:none; }
.simple { list-style-type:none; }
.valtop { vertical-align:top; }
.valmid { vertical-align:middle; }
.valbot { vertical-align:bottom; }

.code { border-style:solid; border-width:0 0 0 1px; padding-left:1em;
        font-family:monospace; white-space:pre; }
.block { }
.blockof { margin:0.4em 2em 0.5em 2em; }
.example { border-style:dashed; border-width:0 0 0 1px; padding-left:1em;
           margin-top:0.5em; margin-bottom:0.5em; white-space:pre; }
.indent { margin-left:2em; margin-right:2em; }
.noindent { margin-left:0; margin-right:0; }
.inblock { display:inline-block; }
.mono { white-space:pre; font-family:monospace; }
.note { margin:0.4em 2em 0.5em 2em; page-break-inside:avoid; }
.note h5 { margin-top:0 }
.note_hr { width:80%; border:1px solid gray; }
.prop { padding-left:1em; margin-top:0.5em; margin-bottom:0.5em; }
.quote { border-style:dashed; border-width:0 0 0 1px; padding-left:1em;
         margin-top:0.5em; margin-bottom:0.5em; }
.this { display:none; }

a:link,a:visited { color:black; text-decoration:none; }
a:hover,a:active { text-decoration:underline; }
a:focus { outline:0; } 

:target:before { content:''; display:block; height:0.1em; margin:-0.1em; }
a.link:link, a.link:visited,a.link:active 
{ color:midnightBlue; text-decoration:underline; text-decoration-style:solid; }

.TOC1cols1 { width:80%; max-width:80%; }
.TOC1cols2 { column-count:2; width:80%; max-width:80%; }
.TOC1cols3 { column-count:3; max-width:90%; max-width:90%; }
.TOC1cols4 { column-count:4; max-width:100%; max-width:100%; }
.TOC1table { margin-left:2em; white-space:nowrap; break-inside:auto; }
.TOC1table tr { vertical-align:top; text-align:left; break-inside:avoid; break-after:auto; }
.TOC1table td+td { padding:0 0 0 0.5em; }
.TOC1table .numb { width:3em; max-width:3em; }
.TOC1table .sepr { width:5em; max-width:6em; overflow:hidden; }
.TOC1table .majr { font-weight:bold; }
.TOC1table .text { white-space:normal; }

/* These are due to Firefox (at least <= 76) recalcitrant multi-column handling.
   Web search "Split table into css columns, issue in Firefox" (stackoverflow).
   "Good grief, Charlie Brown!" */
 
.TOC1cols2 table,
.TOC1cols2 tbody,
.TOC1cols2 tr,
.TOC1cols3 table,
.TOC1cols3 tbody,
.TOC1cols3 tr,
.TOC1cols4 table,
.TOC1cols4 tbody,
.TOC1cols4 tr { display:block; padding:0; }

.TOC2cols1 { width:60%; max-width:60%; }
.TOC2cols2 { column-count:2; width:70%; max-width:70%; }
.TOC2cols3 { column-count:3; width:80%; max-width:80%; }
.TOC2cols4 { column-count:4; width:90%; max-width:90%; }
.TOC2table { margin-left:2em; white-space:nowrap; break-inside:auto; }
.TOC2table tr { vertical-align:top; text-align:left; break-inside:avoid; break-after:auto; }
.TOC2table .numb { font-weight:bold; padding-right:0.5em; }
.TOC2table .text { width:100%; white-space:normal; }

/* see "recalcitrant" above */
.TOC2cols2 table,
.TOC2cols2 tbody,
.TOC2cols2 tr,
.TOC2cols3 table,
.TOC2cols3 tbody,
.TOC2cols3 tr,
.TOC2cols4 table,
.TOC2cols4 tbody,
.TOC2cols4 tr { display:block; padding:0; }

.NAVtable { margin:0.1em 0 0 2em; }
.NAVtable td { font-size:110%; font-weight:bold; padding:0; margin:0; }
.NAVtable a { padding:0 0.5em 0 0.5em; text-decoration:none; }

.IDXcols1 { width:80%; max-width:80%; }
.IDXcols2 { column-count:2; width:90%; max-width:90%; }
.IDXcols3 { column-count:3; width:95%; max-width:95%;  }
.IDXcols4 { column-count:4; width:100%; max-width:100%;  }
.IDXtable { margin:1em 0 1em 2em; white-space:nowrap; break-inside:auto; }
.IDXtable tr { vertical-align:top; text-align:left; break-inside:avoid; break-after:auto; }
.IDXtable .alpha { font-weight:bold; min-width:2em; }
.IDXtable .text  { width:100%; white-space:normal; }
.IDXtable .para:before { content:'\00b6\00a0'; }

/* see "recalcitrant" above */
.IDXcols2 table,
.IDXcols2 tbody,
.IDXcols2 tr,
.IDXcols3 table,
.IDXcols3 tbody,
.IDXcols3 tr,
.IDXcols4 table,
.IDXcols4 tbody,
.IDXcols4 tr { display:block; padding:0; }

.insight { background-color:cyan; font-family:monospace;
           padding:0 0.2em 0 0.2em; margin:0 0.2em 0 0.2em;
           font-size:100%; font-style:normal; font-weight:normal;
           text-decoration:none; }

.wasdoc { font-family: "Lucida Console", Monaco, monospace; 
          letter-spacing:-0.07em; }

@media screen { .blank::after { content:"\2924"; } 
                .print { display:none; }
}

@media print {
   table { page-break-inside:avoid; }
   .noprint { display:none; }
   .page { border:none; page-break-after: always; }
   .epage { display:none; }
   .ppage { page-break-after:always; }
   .NAVtable { display:none; }
   .NAVprint { display:block!important; }
}

@page { margin:2cm 1cm 2cm 1cm;  }
</style>
<!-- source:0000_config.wasdoc -->

<style type="text/css">._smiley::after { font-size:150%; vertical-align:middle; content:'\263a' }</style>
<style type="text/css">._frowny::after { font-size:150%; vertical-align:middle; content:'\2639' }</style>

<a id="0." href="#"></a>
<title>WASD Configuration &ndash; Conditional Configuration</title>
<a id="5." href="#"></a>
<a id="5.conditionalconfiguration" href="#"></a>
<a id="conditionalconfiguration" href="#"></a>
<h1 class="head chunk">WASD Configuration</h1>
<h1 class="head"><span class="numb">5.</span><span class="text">Conditional Configuration</span></h1>

<div class="TOC2cols2">
<table class="TOC2table">
<tr><td><a href="config005.html#5.1.serviceconditionals"><span class="numb">5.1</span><span class="text">Service Conditionals</span></a>
<tr><td><a href="config005.html#5.2.ifendifconditionals"><span class="numb">5.2</span><span class="text">If..endif Conditionals</span></a>
<tr><td><a href="config005.html#5.3.conditionalkeywords"><span class="numb">5.3</span><span class="text">Conditional Keywords</span></a>
<tr><td><a href="config005.html#5.3.1.notepadkeyword"><span class="numb">5.3.1</span><span class="text">Notepad: Keyword</span></a>
<tr><td><a href="config005.html#5.3.2.randkeyword"><span class="numb">5.3.2</span><span class="text">Rand: Keyword</span></a>
<tr><td><a href="config005.html#5.3.3.requestkeyword"><span class="numb">5.3.3</span><span class="text">Request: Keyword</span></a>
<tr><td><a href="config005.html#5.3.4.instanceandrobinkeywords"><span class="numb">5.3.4</span><span class="text">Instance: and Robin: Keywords</span></a>
<tr><td><a href="config005.html#5.3.5.timekeyword"><span class="numb">5.3.5</span><span class="text">Time: Keyword</span></a>
<tr><td><a href="config005.html#5.3.6.trnlnmkeyword"><span class="numb">5.3.6</span><span class="text">Trnlnm: Keyword</span></a>
<tr><td><a href="config005.html#5.3.7.hostaddresses"><span class="numb">5.3.7</span><span class="text">Host Addresses</span></a>
<tr><td><a href="config005.html#5.4.examples"><span class="numb">5.4</span><span class="text">Examples</span></a>
<tr><td><a href="config005.html#5.5.dictionary"><span class="numb">5.5</span><span class="text">Dictionary</span></a>
<tr><td><a href="config005.html#5.5.1.configurationentries"><span class="numb">5.5.1</span><span class="text">Configuration Entries</span></a>
<tr><td><a href="config005.html#5.5.2.otherentries"><span class="numb">5.5.2</span><span class="text">Other Entries</span></a>
<tr><td><a href="config005.html#5.5.3.entrysubstitution"><span class="numb">5.5.3</span><span class="text">Entry Substitution</span></a>
<tr><td><a href="config005.html#5.5.4.watchdictionary"><span class="numb">5.5.4</span><span class="text">WATCH Dictionary</span></a>
</table>
</div>

<table class="NAVtable NAVprint"><tr>
<td><a href="javascript:window.history.back();">&#8617;&#xFE0E;</a>
<td><a href="config004.html#4.">&#8598;&#xFE0E;</a>
<td><a href="config000.html#0.">&#8593;&#xFE0E;</a>
<td><a href="config006.html#6.">&#8600;&#xFE0E;</a>
<td><a href="javascript:window.history.forward();">&#8618;&#xFE0E;</a>
</table>

<p> Request processing (WASD_CONFIG_MAP) and authorization (WASD_CONFIG_AUTH)
rules may be conditionally applied depending on request, server or other
charactersistics. These include

<ul class="list simple list0">
<li class="item"> server host name, port
<li class="item"> client IP address and host name
<li class="item"> browser-accepted content-types, character sets, languages, encodings
<li class="item"> browser identification string
<li class="item"> scheme (&quot;http:&quot; or &quot;https:&quot;, i.e. is it a secure request?)
<li class="item"> HTTP method (GET, POST, etc.)
<li class="item"> request path, query string, cookie data, refering page
<li class="item"> virtual host:port specified in request header
<li class="item"> system information (hardware, Alpha/IA64/X86, node name, VMS version, etc.)
<li class="item"> local time
<li class="item"> random number generation
</ul>

<a id="5.1" href="#"></a>
<a id="5.1.serviceconditionals" href="#"></a>
<a id="serviceconditionals" href="#"></a>
<h2 class="head"><span class="numb">5.1</span><span class="text">Service Conditionals</span></h2>

<p> As described in <a class="link" href="config002.html#2.3.1.virtualserver">2.3.1 [[virtual-server]]</a> a [[<span class="high italic">host</span>:<span class="high italic">port</span>]] rule
applies subsequent configuration depending  on whether the request service
matches the specified service.  This makes it a fundamental element of
conditional configuration.

<p> Note that service conditionals impose a boundary on the scope of
<span class="high italic">if..endif</span> constructs.  That is, an <span class="high italic">if..endif</span> may not span a virtual
service conditional.  A conditional flow syntax error is reported if an
<span class="high italic">if..endif</span> construct is not properly closed before encountering a subsequent
[[<span class="high italic">host</span>:<span class="high italic">port</span>]] rule.

<a id="5.2" href="#"></a>
<a id="5.2.ifendifconditionals" href="#"></a>
<a id="ifendifconditionals" href="#"></a>
<h2 class="head"><span class="numb">5.2</span><span class="text">If..endif Conditionals</span></h2>

<p> These may be nested up to a maximum depth of eight, are not case sensitive
and generally match via string comparison, although some tests are performed as
boolean operations, by converting the conditional parameter to a number before
comparison, and IP address parameters will accept a network mask as well as a
string pattern.

<a id="5.2.0.0.1" href="#"></a>
<a id="5.2.stringmatching" href="#"></a>
<a id="stringmatching" href="#"></a>
<h5 class="head"><span class="text">String Matching</span></h5>

<p> The basis of much conditional decision making is string pattern matching. 
Both wildcard and regular expression based pattern  matching is available
(<a class="link" href="config004.html#4.stringmatching">4. String Matching</a>).  Wildcard matching in conditional tests is
<span class="high italic">greedy</span>.  Regular expression matching, in common with usage throughout WASD,
is differentiated from wildcard patterns using a leading &quot;^&quot; character.

<a id="5.2.0.0.2" href="#"></a>
<a id="5.2.conditionalsyntax" href="#"></a>
<a id="conditionalsyntax" href="#"></a>
<h5 class="head"><span class="text">Conditional Syntax</span></h5>

<p> Conditional expressions and processing flow structures may be used in the
following formats.  Conditional and rule text may be indented for clarifying
structure.

<div class="blockof code"><span class="high bold">if (<span class="high italic">condition</span>)</span> then apply rest of line

<span class="high bold">if (<span class="high italic">condition</span>)</span>
   then apply one
   or more rules
   up until the corresponding &hellip;
<span class="high bold">endif</span>

<span class="high bold">if (<span class="high italic">condition</span>)</span>
   then apply one
   or more rules
<span class="high bold">else</span>
   apply one or more other rules
   up until the corresponding &hellip;
<span class="high bold">endif</span>

<span class="high bold">if (<span class="high italic">condition</span>)</span>
   then apply one
   or more rules
<span class="high bold">elif (<span class="high italic">condition</span>)</span>
   apply one or more other rules
   in a sort or case statement
<span class="high bold">else</span>
   a possible default rule or rules
   up until the delimiting
<span class="high bold">endif</span>
</div>

<p> Logical operators are also supported, in conjunction with precedence
ordering parentheses, allowing moderately complex compound expressions to be
applied in conditionals.

<table class="tabl">
<tr class="tabr">
<th class="tabh monosp">!
<td class="tabd">logical negation
<tr class="tabr">
<th class="tabh monosp">&amp;&amp;&nbsp;&nbsp;&nbsp;
<td class="tabd">logical AND
<tr class="tabr">
<th class="tabh monosp">&verbar;&verbar;
<td class="tabd">logical OR
</table>

<p> There are two more conditional structures that allow previous decisions to
be reused.  These are <span class="high italic">unif</span> and the <span class="high italic">ifif</span>.  The first
unconditionally includes rules regardless of the current state of execution. 
The second resumes execution only if the previous <span class="high italic">if</span> or
<span class="high italic">elif</span> expression was true.  The <span class="high italic">else</span> statement may also
be used after an <span class="high italic">unif</span> to continue only if the previous expression
was false.  The purpose of these constructs are to allow a single decision
statement to include both conditional and unconditional rules.

<div class="blockof code"><span class="high bold">if (<span class="high italic">condition</span>)</span>
   then apply one
   or more rules
<span class="high bold">unif</span>
   apply this block of rules
   unconditionally
<span class="high bold">ifif</span>
   applied only if the original
   if expression was evaulated as true
<span class="high bold">unif</span>
   apply another block of rules
   unconditionally
<span class="high bold">else</span>
   and this block of rules
   only if the original was false
<span class="high bold">endif</span>
</div>

<div class="note">
<a id="5.2.0.0.3" href="#"></a>
<a id="5.2.cautions" href="#"></a>
<a id="cautions" href="#"></a>
<h5 class="head center"><span class="text">CAUTIONS</span></h5>
<hr class="note_hr">

Conditional syntax is checked at rule load time (either server startup or
reload).  Basic errors such as unknown keywords and unbalanced parentheses or
structure statements will be detected and reported to the corresponding Admin
Menu report and to the server process log.
Unless these reports are checked after modifying rule sets syntax errors may
result in unexpected mappings or access.

<p> Although the server cannot determine
the correct intent of an otherwise syntactically correct conditional, if it
encounters an unexpected but detectable condition during processing it aborts
the request, supplying an appropriate error message.

<p> Flow control errors (e.g. an <span class="high italic">if</span> not closed by a subsequent
<span class="high italic">endif</span>) abort all rule processing and provide a fatal error report
to the client.

<hr class="note_hr">
</div>

<a id="5.3" href="#"></a>
<a id="5.3.conditionalkeywords" href="#"></a>
<a id="conditionalkeywords" href="#"></a>
<h2 class="head"><span class="numb">5.3</span><span class="text">Conditional Keywords</span></h2>

<p> The following keywords provide a match between the corresponding request or
other value and a string immediately following the delimiting colon.  White
space or other reserved characters may not be included unless preceded by a
backslash.  The actual value being used in the conditional matching may be
observed using the mapping item of the WATCH facility.

<a id="5.3.0.0.1" href="#"></a>
<a id="5.3.conditionalkeywords" href="#"></a>
<a id="conditionalkeywords" href="#"></a>
<h5 class="head"><span class="text">Conditional Keywords</span></h5>

<table class="tabl">
<tr class="tabr under">
<th class="tabh">Keyword
<th class="tabh">Description
<tr class="tabr">
<tr class="tabr backlight">
<td class="tabd">accept:
<td class="tabd">Browser-accepted content types as listed in the &quot;Accept:&quot; request
header field.  Same string as provided in CGI variable HTTP_ACCEPT.
<tr class="tabr">
<td class="tabd">accept-charset:
<td class="tabd">Browser-accepted character sets as listed in the &quot;Accept-Charset:&quot;
request header field.  CGI variable HTTP_ACCEPT_CHARSET.
<tr class="tabr backlight">
<td class="tabd">accept-encoding:
<td class="tabd">Browser-accepted content encoding as listed in the
&quot;Accept-Encoding:&quot; request header field.  CGI variable
HTTP_ACCEPT_ENCODING.
<tr class="tabr">
<td class="tabd">accept-language:
<td class="tabd">Browser language preferences as listed in the
&quot;Accept-Language:&quot; request header field.  CGI variable
HTTP_ACCEPT_LANGUAGE.
<tr class="tabr backlight">
<td class="tabd">authorization:
<td class="tabd">The raw authorization string from the request header, if any supplied. 
This could be simply used to test whether it has been supplied or not.
<tr class="tabr">
<td class="tabd">callout:
<td class="tabd">Simple boolean value. If a script callout is in progress (see &quot;Scripting
Overview, CGI Callouts&quot;.) it is true, otherwise false.
<tr class="tabr backlight">
<td class="tabd">client_connect_gt:
<td class="tabd">An integer representing the current network connections (those currently being
processed plus those currently being &quot;kept alive&quot;) for the particular client
represented by the current request.  If greater than this value returns true,
otherwise false.
See <a class="link" href="config002.html#2.6.clientconcurrency">2.6 Client Concurrency</a>.
<tr class="tabr">
<td class="tabd">cluster_member:
<td class="tabd">If the supplied node name is (perhaps currently) a member of the cluster (if
any) the server may be executing on.
<tr class="tabr backlight">
<td class="tabd">command_line:
<td class="tabd">The command line qualifiers and parameters used when the server image was
activated.
<tr class="tabr">
<td class="tabd">cookie:
<td class="tabd">Raw cookie data as the text string provided in &quot;Cookie:&quot; request header field. 
CGI variable HTTP_COOKIE.
<tr class="tabr backlight">
<td class="tabd">decnet:
<td class="tabd">Whether DECnet is active on the system and which version is available.  This
value will be 0 if not active, 4 if PhaseIV or 5 is PhaseV.
<tr class="tabr">
<td class="tabd">dict:
<td class="tabd">Matches the specified dictionary entry.
See <a class="link" href="config005.html#5.5.4.watchdictionary">5.5.4 WATCH Dictionary</a>.
<tr class="tabr backlight">
<td class="tabd">directory:
<td class="tabd">Tests whether the specified directory exists or not.  Parameter can be a URI
available for mapping by the server or a VMS file-system specification.  If no
parameter is supplied the request path is mapped to a file-system
specification.  As this conditional accesses the file-system it can be
<span class="high italic">relatively expensive in terms of server latency</span>.
<tr class="tabr">
<td class="tabd">document_root:
<td class="tabd">The DOCUMENT_ROOT CGI variable SET using the
<span class="high italic">map=root=&lt;string&gt;</span> mapping rule.
<tr class="tabr backlight">
<td class="tabd">file:
<td class="tabd">Tests whether the specified file exists or not.  Parameter can be a URI
available for mapping by the server or a VMS file-system specification.  If no
parameter is supplied the request path is mapped to a file-system
specification.  The specification can be a directory.  As this conditional
accesses the file-system it can be <span class="high italic">relatively expensive in terms of
server latency</span>.
<tr class="tabr">
<td class="tabd">forwarded:
<td class="tabd">Proxy/gateway host(s) request forwarded by, as specified in request header
field &quot;Forwarded:&quot;.  CGI variable HTTP_FORWARDED.
<tr class="tabr backlight">
<td class="tabd">host:
<td class="tabd">The host (and optionally port) specified in request header &quot;Host:&quot;
field.  This is used by all modern browsers to provide virtual host information
to the server.  CGI variable HTTP_HOST.
<tr class="tabr">
<td class="tabd">http2:
<td class="tabd">Is true if the request is being transported using HTTP/2
<tr class="tabr backlight">
<td class="tabd">instance:
<td class="tabd">Used to check whether a particular, clustered instance of WASD is available. 
See <a class="link" href="config005.html#5.3.4.instanceandrobinkeywords">5.3.4 Instance: and Robin: Keywords</a>.
<tr class="tabr">
<td class="tabd">jpi_username:
<td class="tabd">The account username the server is executing as.
<tr class="tabr backlight">
<td class="tabd">mapped_path:
<td class="tabd">The path resulting from mapping (phase 2 if script path involved) from which
the path-translated is derived.
<tr class="tabr">
<td class="tabd">multihome:
<td class="tabd">Somewhat specialised conditional that becomes non-null when a client used a
different IP address to connect to the service than the is bound to.  Is set to
the IP address the client used and may be matched using wildcard matching or as
a network mask.
<tr class="tabr backlight">
<td class="tabd">note:
<td class="tabd">Ad hoc information (string) provided by the server administrator using the
/DO=NOTE= facility (and online equivalent) that can be used to quickly and
easily modify rule processing on a per-system or per-cluster basis.
<tr class="tabr">
<td class="tabd">notepad:
<td class="tabd">Information (strings) stored using the SET <span class="high italic">notepad=</span> mapping rule.
See <a class="link" href="config005.html#5.3.1.notepadkeyword">5.3.1 Notepad: Keyword</a>.
<tr class="tabr backlight">
<td class="tabd">ods:
<td class="tabd">Specified as 2 or 5 (Extended File System), or as SRI file name encoding
(MultiNet NFS and others) PWK encoding (PATHWORKS 4/5), ADS encoding
(Advanced Server / PATHWORKS 6), SMB encoding (Samba - same as ADS).
<tr class="tabr">
<td class="tabd">pass:
<td class="tabd">A numeric value, 1 or 2, representing the first or second pass (if a script
component was parsed) through the path mapping rules.  Will be zero at other
times.  When the server is <span class="high italic">reverse-mapping</span> a file specification
will be -1.
<tr class="tabr backlight">
<td class="tabd">path-info:
<td class="tabd">Path specified in the request line.  CGI variable PATH_INFO.
<tr class="tabr">
<td class="tabd">path-translated:
<td class="tabd">VMS translation of path-info.  Available after rule mapping (i.e. during
authorization rule processing).
<tr class="tabr backlight">
<td class="tabd">proctor:
<td class="tabd">Simple boolean value.  If a proctored script this is true (see
<a class="link blank" target="_blank" href="../scripting/#scriptproctor">Script Proctor</a> in <a class="link blank" target="_blank" href="../scripting/#0.">WASD Scripting</a>).
<tr class="tabr">
<td class="tabd">query-string:
<td class="tabd">Query string specified in request line.  Same information as provided in
CGI variable QUERY_STRING.
<tr class="tabr backlight">
<td class="tabd">rand:
<td class="tabd">Value from a random number generator.
See <a class="link" href="config005.html#5.3.2.randkeyword">5.3.2 Rand: Keyword</a>.
<tr class="tabr">
<td class="tabd">redirected:
<td class="tabd">If a request has been internally redirected
(<a class="link" href="config010.html#10.5.2.redirectrule">10.5.2 REDIRECT Rule</a>) this conditional will be non-zero.  Can
be used as a boolean or with a digit specified.
<tr class="tabr backlight">
<td class="tabd">referer:
<td class="tabd">URL of refering page as provided in &quot;Referer:&quot; request header field. 
CGI variable HTTP_REFERER.
<tr class="tabr">
<td class="tabd">regex:
<td class="tabd">Simple boolean value.  If configuration directive [RegEx] is enabled (and hence
regular expression string matching, <a class="link" href="config004.html#4.stringmatching">4. String Matching</a>) this
will be true.
<tr class="tabr backlight">
<td class="tabd">remote-addr:
<td class="tabd">Client IP address.  Same as provided as CGI variable REMOTE_ADDR.  As
with all IP addresses used for conditional testing this may be wildcard string
match or network mask expressed as <span class="high italic">address</span>/<span class="high italic">mask-length</span>
(see <a class="link" href="config005.html#5.3.7.hostaddresses">5.3.7 Host Addresses</a>).  A domain (host) name
preceded by a question point may be specified (e.g. &quot;?the.host.name&quot;). 
The corresponding IP address is  then looked up and compared to the client. 
This allows ad hoc host name based rules and is distinct from use of
<span class="high italic">remote-host</span>.  Note that DNS lookup can introduce some latency to
rule (and request) processing.
<tr class="tabr">
<td class="tabd">remote-host:
<td class="tabd">Client host name if name resolution enabled, otherwise the IP address (same
as <span class="high italic">remote-addr</span>).
CGI variable REMOTE_HOST.
<tr class="tabr backlight">
<td class="tabd">request:
<td class="tabd">Detect the presence of specific or unknown request fields.
See <a class="link" href="config005.html#5.3.3.requestkeyword">5.3.3 Request: Keyword</a>.
<tr class="tabr">
<td class="tabd">request-method:
<td class="tabd">HTTP method (&quot;GET&quot;, &quot;POST&quot;, etc.) specified in the request
line.  CGI variable REQUEST_METHOD.
<tr class="tabr backlight">
<td class="tabd">request-protocol:
<td class="tabd">Detect the HTTP protocol in use for the request, as &quot;2&quot;, &quot;1.1&quot;,
&quot;1.0&quot; or &quot;0.9&quot;.  Note that the <span class="high italic">server-protocol</span>
conditional will indicate 1.1 when the <span class="high italic">request-protocol</span> indicates
2.  The server and its applications (scripts) still treat it semantically
as HTTP/1.1.
<tr class="tabr">
<td class="tabd">request-scheme:
<td class="tabd">Request protocol as &quot;http:&quot; or &quot;https:&quot;.   CGI variable
REQUEST_SCHEME.
<tr class="tabr backlight">
<td class="tabd">request-uri:
<td class="tabd">The unescaped request path plus any query-string.  CGI variable REQUEST_URI.
<tr class="tabr">
<td class="tabd">restart:
<td class="tabd">A numeric value, zero to maximum, representing the number of times path mapping
has been SET <span class="high italic">map=restart</span>.   Can be used as a boolean or with a
digit specified.
<tr class="tabr backlight">
<td class="tabd">robin:
<td class="tabd">Used to check whether a particular, clustered instance of WASD is available and
distribute requests to it using a round-robin algorithm. 
See <a class="link" href="config005.html#5.3.4.instanceandrobinkeywords">5.3.4 Instance: and Robin: Keywords</a>.
<tr class="tabr">
<td class="tabd">script-name:
<td class="tabd">After the first pass of rule mapping (script component resolution), or during
authorization processing, any script component of the request URI.
<tr class="tabr backlight">
<td class="tabd">server-addr:
<td class="tabd">The service IP address.  CGI variable SERVER_ADDR.
This may be wildcard string match or network mask expressed as
<span class="high italic">address</span>/<span class="high italic">mask-length</span>.
<tr class="tabr">
<td class="tabd">server_connect_gt:
<td class="tabd">An integer representing the current server network connections (those currently
being processed plus those currently being &quot;kept alive&quot;).  If greater than this
value returns true, otherwise false.
<tr class="tabr backlight">
<td class="tabd">server_process_gt:
<td class="tabd">An integer representing the current server requests in-progress.  If greater
than this value returns true, otherwise false.
<tr class="tabr">
<td class="tabd">server-name:
<td class="tabd">The (possibly virtual) server name.  This may or may not exactly match any
string provided via the <span class="high italic">host</span> keyword.  CGI variable SERVER_NAME.
<tr class="tabr backlight">
<td class="tabd">server-port:
<td class="tabd">The (possibly virtual) server port number.  CGI variable SERVER_PORT.
<tr class="tabr">
<td class="tabd">server-protocol:
<td class="tabd">&quot;1.1&quot;, &quot;1.0&quot;, &quot;0.9&quot; representing the HTTP protocol used by
the request.
<tr class="tabr backlight">
<td class="tabd">server-software:
<td class="tabd">The server identification string, including the version.  For example
&quot;HTTPd-WASD/8.0.0 OpenVMS/AXP SSL&quot;.  CGI variable SERVER_SOFTWARE.
<tr class="tabr">
<td class="tabd">service:
<td class="tabd">This is the composite server name plus port as
<span class="high italic">server-name</span>:<span class="high italic">port</span>.  To match an unknown service use
&quot;?&quot;.
<tr class="tabr backlight">
<td class="tabd">ssl:
<td class="tabd">Simple boolean value.  If request is via Secure Sockets Layer then this
will be true.
<tr class="tabr">
<td class="tabd">syi_arch_name:
<td class="tabd">System information; CPU architecture of the server system, &quot;Alpha&quot;,
&quot;Itanium&quot; or &quot;x86-64&quot;.
<tr class="tabr backlight">
<td class="tabd">syi_hw_name:
<td class="tabd">System information; hardware identification string, for example
&quot;AlphaStation 400 4/233&quot;.
<tr class="tabr">
<td class="tabd">syi_nodename:
<td class="tabd">System information; the node name, for example &quot;KLAATU&quot;.
<tr class="tabr backlight">
<td class="tabd">syi_version:
<td class="tabd">System information; VMS version string, for example &quot;V7.3&quot;.
<tr class="tabr">
<td class="tabd">tcpip:
<td class="tabd">A string derived from the UCX&dollar;IPC_SHR shareable image. It looks something like
this &quot;Compaq TCPIP&dollar;IPC_SHR V5.1-15 (11-JAN-2001 02:28:33.95)&quot; and comprises the
agent (Compaq, MultiNet, TCPware, unknown), the name of the image, the version
and finally the link date.
<tr class="tabr backlight">
<td class="tabd">time:
<td class="tabd">Compare to current system time.  See <a class="link" href="config005.html#5.3.5.timekeyword">5.3.5 Time: Keyword</a>.
<tr class="tabr">
<td class="tabd">trnlnm:
<td class="tabd">Translate a logical name.  See <a class="link" href="config005.html#5.3.6.trnlnmkeyword">5.3.6 Trnlnm: Keyword</a>.
<tr class="tabr backlight">
<td class="tabd">upstream-addr:
<td class="tabd">Client proxy/accelerator IP address, when &quot;SET CLIENT=keyword&quot; has been applied
to enable transparent up-stream proxy.  Same as provided as CGI variable 
UPSTREAM_ADDR.  As  with all IP addresses used for conditional testing this may
be wildcard string match or network mask expressed as
<span class="high italic">address</span>/<span class="high italic">mask-length</span> (see <a class="link" href="config005.html#5.3.7.hostaddresses">5.3.7 Host Addresses</a>).
<tr class="tabr">
<td class="tabd">user-agent:
<td class="tabd">Browser identification string as provided in &quot;User-Agent:&quot; request
header field.  CGI variable HTTP_USER_AGENT.
<tr class="tabr backlight">
<td class="tabd">webdav:
<td class="tabd">Simple boolean value.  If the request has been identified as WebDAV then this
is true. Takes an optional parameter:

<table class="tabl">
<tr class="tabr">
<td class="tabd">webdav:all
<td class="tabd">True if path has been <span class="high italic">SET webdav=all</span>
<tr class="tabr">
<td class="tabd">webdav:auth
<td class="tabd">True if path has been <span class="high italic">SET webdav=auth</span>
<tr class="tabr">
<td class="tabd">webdav:MSagent
<td class="tabd">True if a Microsoft WebDAV agent has been detected.

</table>
<tr class="tabr">
<td class="tabd">websocket:
<td class="tabd">Simple boolean value.  If a WebSocket protocol upgrade request will be true.
<tr class="tabr backlight">
<td class="tabd">x-forwarded-for:
<td class="tabd">Proxied client name or address as provided in &quot;X-Forwarded-For:&quot; request
header field.  CGI variable HTTP_X_FORWARDED_FOR. 

</table>

<a id="5.3.1" href="#"></a>
<a id="5.3.1.notepadkeyword" href="#"></a>
<a id="notepadkeyword" href="#"></a>
<h3 class="head"><span class="numb">5.3.1</span><span class="text">Notepad: Keyword</span></h3>

<p> The <span class="high italic">request notepad</span> is a string storage area that can be used to store
and retrieve ad hoc information during path mapping and subsequent
authorization processing.  The notepad contents can be changed using the SET
<span class="high italic">notepad=&lt;string&gt;</span> or appended to using SET <span class="high italic">notepad=+&lt;string&gt;</span> (<a class="link" href="config010.html#10.5.5.setrule">10.5.5 SET Rule</a>).  These contents then can be  subsequently detected using the
<span class="high italic">notepad:</span> conditional keyword (or the obsolescent 'NO' mapping conditional)
and used to control subsequent mapping or authorization processing.

<p> Notepad information persists across internal redirection processing
(<a class="link" href="config010.html#10.5.2.redirectrule">10.5.2 REDIRECT Rule</a>) and so may be used when the regenerated request is
mapped and authorized.  To prevent such information from unexpectedly
interfering with internally redirected requests a <span class="high italic">notepad=&quot;&quot;</span> can be used to
empty the storage area.

<p> The <span class="high italic">dictionary</span> facility provides similar and arguably superior
functionailtiy.  See <a class="link" href="config005.html#5.5.4.watchdictionary">5.5.4 WATCH Dictionary</a>.  In fact <span class="high italic">notepad</span> is now
implemented as a dictionary entry.

<a id="5.3.2" href="#"></a>
<a id="5.3.2.randkeyword" href="#"></a>
<a id="randkeyword" href="#"></a>
<h3 class="head"><span class="numb">5.3.2</span><span class="text">Rand: Keyword</span></h3>

<p> At the commencement of each pass a new pseudo-random number is generated
(and therefore remains constant during that pass).  The  <span class="high italic">rand:</span>
conditional is intended to allow some sort of distribution to be built into a
set of rules, where each pass (request) generates a different one.  The random
conditional accepts two parameters, a <span class="high italic">modulas</span> number, which is used
to modulas the base number, and a <span class="high italic">comparison</span> number, which is
compared to the modulas result.

<p> Hence the following conditional rules
<div class="blockof code">if (rand:3:0)
   <span class="high italic">do this</span>
elif (rand:3:1)
   <span class="high italic">do this</span>
else
   <span class="high italic">do this</span>
endif
</div>
would pseudo-randomly generate base numbers of 0, 1, 2 and perform the
appropriate conditional block.  Over a sufficient number of usages this should
produce a relatively even distribution of numbers.  If the modulas is specified
as less than two (i.e. no distribution factor at all) it defaults to 2 (i.e. a
distribution of 50%).  Hence the following example should be the equivalent of
a coin toss.
<div class="blockof code">if (rand:)
   <span class="high italic">heads</span>
else
   <span class="high italic">tails</span>
endif
</div>

<a id="5.3.3" href="#"></a>
<a id="5.3.3.requestkeyword" href="#"></a>
<a id="requestkeyword" href="#"></a>
<h3 class="head"><span class="numb">5.3.3</span><span class="text">Request: Keyword</span></h3>

<p> Looks through each of the lines of the request header for the specified
request field and/or value.  This may be used to detect the presence of
specific or unknown (to the server) request fields.  When detecting a specified
just field the name can be provided
<div class="blockof code">if (request:&quot;Keep-Alive:*&quot;)
</div>
matching any value, or specific values can also be matched for
<div class="blockof code">if (request:&quot;User-Agent:*Opera*&quot;)
</div>

<p> Note that all request fields known to the server have a specific associated
conditional keyword (i.e. &quot;user-agent:&quot; for the above example).  To
determine whether any request fields unknown to the server have been supplied
use the <span class="high italic">request:</span> keyword as in the following example.
<div class="blockof code">if (request:?)
   map * /cgi-bin/unknown_request_notify.com*
endif
</div>

<a id="5.3.4" href="#"></a>
<a id="5.3.4.instanceandrobinkeywords" href="#"></a>
<a id="instanceandrobinkeywords" href="#"></a>
<h3 class="head"><span class="numb">5.3.4</span><span class="text">Instance: and Robin: Keywords</span></h3>

<p> Both of these conditionals are designed to allow the redistribution of
requests between clustered WASD services.  They are WASD-aware and so allow a
slightly more tailored distribution than perhaps an IP package round-robin
implementation might.  Each tests for the current operation of WASD on a
particular node (using the DLM) before allowing the selection of that node as a
target. This can allow some systems to be shutting down or starting up, or have
WASD shutdown for any reason, without requiring any extraordinary procedures
to allow for the change in processing environment.

<a id="5.3.4.0.1" href="#"></a>
<a id="5.3.4.instance" href="#"></a>
<a id="instance" href="#"></a>
<h5 class="head"><span class="text">Instance:</span></h5>

<p> The instance: directive allows testing for a particular
cluster member having a WASD instance currently running.  This can allow
requests to be redirected or reverse-proxied to a particular system with the
knowlege that it should be processed (of course there is a small window of
uncertainty as events such as system shutdown and startup occur
asynchronously).  The behaviour of the conditional block is entirely
determinate based on which node names have a WASD instance and the order of
evaluation.  Compare this to a similar construct using the robin: directive, as
described below.

<p> This conditional is deployed in two phases.  In the first, it contains a
comma-separated list of node names (that are expected to have instances of WASD
instantiated).  In the second, containing a single node name, allowing the
selected node to be tested.  For example.

<div class="blockof code">if (instance:NODE1,NODE2,NODE3)
   if (instance:NODE1) redirect /* http://node1.domain.name/*?
   if (instance:NODE2) redirect /* http://node2.domain.name/*?
   if (instance:NODE3) redirect /* http://node3.domain.name/*?
   pass * &quot;500 Some sort of logic error!!&quot;
endif
pass * &quot;503 No instance currently available!&quot;
</div>

<p> If none of the node names specified in the first phase is currently running
a  WASD instance the rule returns false, otherwise true.  If true the above
example has conditional block processed with each of the node names
successively tested.  If NODE1 has a WASD instance executing it returns true
and the associated redirect is performed.  The same for NODE2 and NODE3.  At
least one of these would be expected to test true otherwise the outer
conditional established during phase one would have been expected to return
false.

<a id="5.3.4.0.2" href="#"></a>
<a id="5.3.4.robin" href="#"></a>
<a id="robin" href="#"></a>
<h5 class="head"><span class="text">Robin:</span></h5>

<p> The robin: conditional allows rules to be applied
sequentially against specified members of a cluster that currently have
instances of WASD running. This is obviously intended to allow a form of load
sharing and/or with redundancy (not balancing, as no evaluation of the selected
target's current workload is performed, see below).  As with the instance:
directive above, there is, of course, a small window of potential uncertainty
as events such as system shutdown and startup occur asynchronously and may
impact availability between the phase one test and ultimate request
distribution.

<p> This conditional is again used in two phases.  The first, containing a
comma-separated list of node names (that are expected to have instances of WASD
instantiated).  The second, containing a single node name, allowing the
selected node (from phase one) to have a rule applied.  For example.

<div class="blockof code">if (robin:X861,ALPHA1,ALPHA2,IA64A)
   if (robin:X861) redirect /* http://x861.domain.name/*?
   if (robin:ALPHA1) redirect /* http://alpha1.domain.name/*?
   if (robin:ALPHA2) redirect /* http://alpha2.domain.name/*?
   if (robin:IA64A) redirect /* http://ia64a.domain.name/*?
   pass * &quot;500 Some sort of logic error!!&quot;
endif
pass * &quot;503 No round-robin node currently available!&quot;
</div>

<p> In this case round-robining will be made through four node names.  Of
course these do not have to represent all the systems in the cluster currently
available or having WASD instantiated.  The first time the 'robin:' rule
containing multiple names is called X861 will be selected.  The second time
ALPHA1, the third ALPHA2, and the fourth IA64A.  With the fifth call X861 is
returned to, the sixth ALPHA1, etc.  In addition, the selected nodename is
verified to have a instance of WASD currently running (using the DLM and WASD's
instance awareness).  If it does not, round-robining is applied again until one
is found (if none is available the phase one conditional returns false).  This
is most significant as it ensures that the selected node should be able to
respond to a redirected or (reverse-)proxied requested.  This is the selection
set-up phase.

<p> Then there is the selection application phase.  Inside the set-up
conditional other conditionals apply the selection made in the first phase
(through simple nodename string comparison).  The rule, in the above example a
redirect, is applied if that was the node selected.

<p> During selection set-up unequal weighting can be applied to the round-robin
algorithm by including particular node names more than once.

<div class="blockof code">if (robin:X861,ALPHA,X862,ALPHA)
</div>

<p> In the above example, the node ALPHA will be selected twice as often as
either of X861 and X862 (and because of the ordering interleaved with the X86
selections).

<a id="5.3.5" href="#"></a>
<a id="5.3.5.timekeyword" href="#"></a>
<a id="timekeyword" href="#"></a>
<h3 class="head"><span class="numb">5.3.5</span><span class="text">Time: Keyword</span></h3>

<p> The <span class="high italic">time:</span> conditional allows server behaviour to change
according to the time of day, week, or even year.  It compares the supplied
parameter to the current system time in one of three ways.

<ol class="list">

<li class="item"> The supplied parameter is in the form &quot;1200-1759&quot;, which should
be read as &quot;twelve noon to five fifty-nine PM&quot; (i.e. as a time range in
minutes, generalized as <span class="high italic">hhmm-hhmm</span>), where the first is the start
time and the second the end time.  If the current time is within that range
(inclusive) the conditional returns true, otherwise false.  If the range
doesn't look correct false is always returned.

<div class="blockof code">if (time:0000-0000)
   <span class="high italic">it's midnight</span>
elif (time:0001-1159)
   <span class="high italic">it's AM</span>
elif (time:1200-1200)
   <span class="high italic">it's noon</span>
else
   <span class="high italic">it's PM</span>
endif
</div>

<li class="item"> If the supplied parameter is a single digit it is compared to the VMS day
of the week (1-Monday, 2-Tuesday &hellip; 7-Sunday).

<div class="blockof code">if (time:6 &verbar;&verbar; time:7)
   <span class="high italic">it's the weekend</span>
else
   <span class="high italic">it's the working week</span>
endif
</div>

<li class="item"> If the supplied string is not in either of the formats described above it
is treated as a string match with a VMS comparision time (i.e.
<span class="high italic">yyyy-mm-dd hh-mm-ss.hh</span>). 

<div class="blockof code">if (time:%%%%-05-*)
   <span class="high italic">it's the month of May</span>
endif
</div>

</ol>

<a id="5.3.6" href="#"></a>
<a id="5.3.6.trnlnmkeyword" href="#"></a>
<a id="trnlnmkeyword" href="#"></a>
<h3 class="head"><span class="numb">5.3.6</span><span class="text">Trnlnm: Keyword</span></h3>

<p> The <span class="high italic">trnlnm:</span> conditional dynamically translates a logical name
and uses the value.  One mandatory and up to two optional parameters may be
supplied.

<div class="blockof code">trnlnm:logical-name[;name-table][:string-to-match]
</div>

<p> The <span class="high italic">logical-name</span> must be supplied; without it false is always
returned.  If just the <span class="high italic">logical-name</span> is supplied the conditional
returns true if the name exists or false if it does not.  The default
<span class="high italic">name-table</span> is LNM&dollar;FILE_DEV.  When the optional
<span class="high italic">name-table</span> is supplied the lookup is confined to that table.  If
the optional <span class="high italic">string-to-match</span> is supplied it is matched against the
value of the logical and the result returned.

<a id="5.3.7" href="#"></a>
<a id="5.3.7.hostaddresses" href="#"></a>
<a id="hostaddresses" href="#"></a>
<h3 class="head"><span class="numb">5.3.7</span><span class="text">Host Addresses</span></h3>

<p> Host names or addresses can be an alpha-numeric string (if DNS lookup is
enabled) or dotted-decimal network address, a slash, then a dotted-decimal
mask.  For example &quot;131.185.250.0/255.255.255.192&quot;. This has a 6 bit
subnet.  It operates by bitwise-ANDing the client host address with the mask,
bitwise-ANDing the network address supplied with the mask, then comparing the
two results for equality.  Using the above example the host 131.185.250.250
would be accepted, but 131.185.250.50 would be rejected. Equivalent notation
for this rule would be &quot;131.185.250.0/26&quot;.

<a id="5.4" href="#"></a>
<a id="5.4.examples" href="#"></a>
<a id="examples" href="#"></a>
<h2 class="head"><span class="numb">5.4</span><span class="text">Examples</span></h2>

<p> The following provides a collection of examples of conditional mapping and
authorization rules illustrating the use of wildcard matching, network mask
matching and the various formats in which the rules may be blocked.

<ol class="list">

<li class="item"> This first example shows an EXEC mapping rule being applied to a path if
the request query string contains the string &quot;example&quot;.

<div class="blockof code">if (query-string:*example*) exec /* /cgi-bin/example/* 
</div>

<li class="item"> In this example a block of mapping statements is processed if the virtual
service of the request matches that in the conditional, otherwise the block is
skipped.  Note the indentation to help clarify the structure.

<div class="blockof code">if (service:the.host.name:80)
   pass /web/* /dka0/the_host_name_web/*
   pass /graphics/* /dka100/graphics/*
   pass * &quot;404 Resource not found.&quot;
endif
</div>

<li class="item"> This example a series of tests allow a form of case processing where the
first to match will be processed and terminate the matching process.  In this
case if a match does not occur rule processing continues after the
<span class="high italic">endif</span>.

<div class="blockof code">if (service:the.host.name:80)
   pass /web/* /dka0/the_host_name_web/*
elif (service:next.host.name:80)
   pass /web/* /dka0/next_host_name_web/*
elif (service:another.host.name:80)
   pass /web/* /dka0/another_host_name_web/*
endif
pass /graphics/* /dka100/graphics/*
pass * &quot;404 Resource not found.&quot;
</div>

<li class="item"> In this (somewhat contrived) example a nested test is used to check
(virtual) server name and that the request is being handled via Secure Sockets
Layer (SSL) for security.  If it is not an informative message is supplied. 
The <span class="high italic">else</span> and the quotes are not really required but included here
for illustration.

<div class="blockof code">if (server-name:the.host.name)
   if (scheme:&quot;https&quot;)
      pass /secure/* /dka0/the_host_name_web/secure/*
   else
      pass * /dka0/the_host_name_web/secure/only-via-SSL.html
   endif
endif
</div>

<li class="item"> This would be another way to accomplish a similar objective to example 4. 
This uses a <span class="high italic">negation</span> operator to exclude access to successive
mappings if not requesting via SSL.

<div class="blockof code">if (server-name:the.host.name)
   if (!SSL:)
      pass * /web/secure/only-via-SSL.html
   endif
   pass /secure/* /web/secure/*
   pass /other/* /web/other/*
   pass /web/* /web/web/*
   pass * &quot;404 Resource not found.&quot;
endif
</div>

<li class="item"> This example shows the use of a compound conditional using the AND and OR
operators.  It also illustrates the use of a network mask.  It will exclude all
access to the specified path unless the request is originating from
within a specified network (perhaps an intranet) or via SSL.

<div class="blockof code">if (path:/sensitive/* &amp;&amp; !(remote-addr:131.185.250.0/24 &verbar;&verbar; SSL:))
   pass * 404 &quot;Access denied (SSL only).&quot;
endif
</div>

<li class="item"> This example illustrates restricting authentication to SSL.

<div class="blockof code">[[*]]
[&quot;Your VMS password&quot;=VMS]
if (!request-scheme:https)
   * r+w,#0
endif
</div>

<li class="item"> Logical name translation may be used to dynamically alter the flow of
rule interpretation.

<div class="blockof code">if (trnlnm:HTTPD_EXAMPLE)
   pass /* /example/*
else
   pass /* /*
endif
</div>

<li class="item"> Using a site administrator's /DO=NOTE= entry to modify rule processing. 
In this example the contingency of a broken back-end processor has been
prepared for and a document advising clients of the temporary problem is
redirected to once the administrator enters

<div class="blockof code">&dollar; HTTPD /DO=NOTE=PROBLEM /ALL
</div>
 at the command-line (or via the online equivalent).  Note that in this
example external clients are provided with the problem advice document while
internal clients may still access the back-end for troubleshooting purposes.

<div class="blockof code">if (note:PROBLEM &amp;&amp; !remote-addr:131.185.0.0/16)
   pass /* /problem_with_backend.html
else
   pass /* /backend/*
endif
</div>

<p> Of course there are a multitude of possibilities based on this idea!

</ol>

<div class="note center"><a id="5.4.0.0.0.1" href="#"></a>
<a id="5.4.note" href="#"></a>
<a id="note" href="#"></a>
<h5 class="head center"><span class="text">Note</span></h5>
<hr class="note_hr">

The noted data persists across server startups but does not persist across
system startups!
<hr class="note_hr">
</div>

<a id="5.5" href="#"></a>
<a id="5.5.dictionary" href="#"></a>
<a id="dictionary" href="#"></a>
<h2 class="head"><span class="numb">5.5</span><span class="text">Dictionary</span></h2>

<p> The per-request dictionary stores key-value string pairs related to request
processing.  Some entries are generated and used internally by the server and
others may be inserted, value changed, removed and tested by the server admin
for conditional processing purposes.

<p> The dictionary was initially introduced as an abstraction layer between the
significantly different HTTP/2 and HTTP/1.<span class="high italic">n</span> header semantics and
server internal processing.  Its utility was then extended into configuration. 
It is implemented as a standard hash table with collision lists.  The small
cost in terms of processing is completely offset by its effectiveness.

<a id="5.5.1" href="#"></a>
<a id="5.5.1.configurationentries" href="#"></a>
<a id="configurationentries" href="#"></a>
<h3 class="head"><span class="numb">5.5.1</span><span class="text">Configuration Entries</span></h3>

<p> Dictionary entries may be configured using the SET dict=<span class="high italic">key</span>=<span class="high italic">value</span>
mapping rule or the DICT <span class="high italic">key</span>=<span class="high italic">value</span> meta keyword.  These are known as 
<span class="high italic">configuration entries</span>.  Keys must begin with an alpha-numeric character but
otherwise keys and values may contain any printable character, with some
needing to be escaped in the text of configuration files.  These are some
examples of each.

<div class="blockof code">set /example/path* dict=example_key=example&nbsp;value
set /example/path* dict=example_key=&quot;example value&quot;
set /example/path* dict=example_key=&quot;example "value"&quot;

dict example_key=example&nbsp;value
dict example_key=&quot;example value&quot;
dict example_key=&quot;example "value"&quot;
</div>

<p> If an existing key is (re-)inserted it overwrites the old value.

<p> An entry can have an empty value.

<div class="blockof code">set /example/path* dict=example_key=
dict example_key=
</div>

<p> An entry may be removed from the dictionary by prefixing the key name with
an exclamation point.

<div class="blockof code">set /example/path* dict=!example_key
dict !example_key
</div>

<p> All configuration entries may be removed by using the exclamation point
with an empty key.

<div class="blockof code">set /example/path* dict=!
dict !
</div>

<div class="note"><a id="5.5.1.0.0.1" href="#"></a>
<a id="5.5.1.note" href="#"></a>
<a id="note" href="#"></a>
<h5 class="head center"><span class="text">Note</span></h5>
<hr class="note_hr">

Configuration entries persist across internal redirection processing
(<a class="link" href="config010.html#10.5.2.redirectrule">10.5.2 REDIRECT Rule</a>) and so may be used as flags or otherwise contain useful
information when the regenerated request is mapped and authorized.  To prevent
such information from unexpectedly interfering with internally redirected
requests selected or all entries can be removed in the redirected request using
the above values.
<hr class="note_hr">
</div>

<a id="5.5.2" href="#"></a>
<a id="5.5.2.otherentries" href="#"></a>
<a id="otherentries" href="#"></a>
<h3 class="head"><span class="numb">5.5.2</span><span class="text">Other Entries</span></h3>

<p> As mentioned, the server generates and uses dictionary entries during
request processing.  There are multiple types of entry, generally insulated
from each other for good reason.  These entries are also available for
conditional testing.

<a id="5.5.2.0.1" href="#"></a>
<a id="5.5.2.dictionaryentries" href="#"></a>
<a id="dictionaryentries" href="#"></a>
<h5 class="head"><span class="text">Dictionary Entries</span></h5>

<table class="tabl">
<tr class="tabr under">
<th class="tabh">Character
<th class="tabh">Type
<th class="tabh">Description
<tr class="tabr">
<tr class="tabr">
<td class="tabd">~
<td class="tabd">configuration
<td class="tabd">admin managed entry
<tr class="tabr">
<td class="tabd">&dollar;
<td class="tabd">internal
<td class="tabd">server processing
<tr class="tabr">
<td class="tabd">&gt;
<td class="tabd">request
<td class="tabd">request header field
<tr class="tabr">
<td class="tabd">&lt;
<td class="tabd">response
<td class="tabd">response header field
</table>

<p> The &quot;if (dict:<span class="high italic">expression</span>)&quot; contruct first checks for a configuration
entry, then for an request header field entry, then finally for an internal
entry (response entries are only available for testing after response
processing begins and so not in the search list).  It is also possible to test
for a key of a specific type by prefixing the key name with the type character. 
This example shows a request header field being conditionally processed.

<div class="blockof code">if (dict:&gt;X-example=hello)
</div>

<p> It is also possible to set an entry of a specific type by prefixing the key
with the type character.  For example the following will set a response header
field that will be included in the header when returned to the client.

<div class="blockof code">set /example/path* dict=&lt;X-example=&quot;"quoted string"&quot;
</div>

<p> Setting any non-configuration entry should only be undertaken by the
literati or the brave.

<a id="5.5.3" href="#"></a>
<a id="5.5.3.entrysubstitution" href="#"></a>
<a id="entrysubstitution" href="#"></a>
<h3 class="head"><span class="numb">5.5.3</span><span class="text">Entry Substitution</span></h3>

<p> The value of a dictionary entry can be derived in whole or part from the
value of another entry or entries.  This uses a somewhat familiar substitution
syntax.  A contrived example shows an entry being set that transfers back the
request user-agent header field as a response header field.

<div class="blockof code">set /example/path* dict=&lt;X-user-agent=''&gt;user-agent'
</div>

A similar rule can be seen applied in the WATCH report example below.

<a id="5.5.4" href="#"></a>
<a id="5.5.4.watchdictionary" href="#"></a>
<a id="watchdictionary" href="#"></a>
<h3 class="head"><span class="numb">5.5.4</span><span class="text">WATCH Dictionary</span></h3>

<p> The content of a request's dictionary at significant stages of request
processing can be viewed using the [x]Internal item of a WATCH report.  See
<a class="link blank" target="_blank" href="../features/#watchfacility">WATCH Facility</a> of
<a class="link blank" target="_blank" href="../features/#0.">WASD Features and Facilities</a>.

<p> A request dictionary WATCH point is similar to the following (end of request
processing) example.  Note that all of the entry types described above are
present in the example, including two configured entries.  Note also that two
of the internal entries contain embedded line-breaks and empty lines.  This is
an HTTP/2 request and the expanded (HTTP/1.<span class="high italic">n</span> style) <span class="high italic">request_header</span> and
<span class="high italic">response_header</span> entries are due to WATCH items Request [x]Header and
Response [x]Header also being checked. They were not required for request
processing.

<div class="blockof code">&verbar;Time_______&verbar;Module__&verbar;Line&verbar;Item&verbar;Category__&verbar;Event...&verbar;
<span class="high italic">8&lt; snip 8&lt;</span>
&verbar;21:11:00.12 DICT     0836 0001 INTERNAL   DICTIONARY size:32 count:29 bytes:4193&verbar;
ENTRY 001 [005] &dollar; {14}request_method={3}GET
ENTRY 002 [009] &dollar; {12}request_path={15}/httpd/-/admin/
ENTRY 003 [014] &gt; {6}accept={63}text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
ENTRY 004 [018] &gt; {15}accept-encoding={13}gzip, deflate
ENTRY 005 [001] &gt; {10}user-agent={116}Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/601.4.4 (KHTML, like Gecko) Version/9.0.3 Safari/601.4.4
ENTRY 006 [007] &gt; {15}accept-language={5}en-us
ENTRY 007 [031] &gt; {13}authorization={30}Basic *************************
ENTRY 008 [004] &gt; {3}dnt={1}1
ENTRY 009 [012] &dollar; {12}request_line={28}GET /httpd/-/admin/ HTTP/1.1
ENTRY 010 [024] &gt; {4}host={18}klaatu.private:443
ENTRY 011 [011] &dollar; {10}http2_ping={6}44.919
ENTRY 012 [013] &dollar; {14}request_header={372}GET /httpd/-/admin/ HTTP/1.1
accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
accept-encoding: gzip, deflate
user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/601.4.4 (KHTML, like Gecko) Version/9.0.3 Safari/601.4.4
accept-language: en-us
authorization: Basic *************************
dnt: 1
host: klaatu.private:443

ENTRY 013 .012. &dollar; {9}path_info={15}/httpd/-/admin/
ENTRY 014 [000] &dollar; {12}query_string={0}
ENTRY 015 .004. &dollar; {11}request_uri={15}/httpd/-/admin/
ENTRY 016 [025] ~ {7}this_is={7}a test!
ENTRY 017 [028] &lt; {12}x-user-agent={116}Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/601.4.4 (KHTML, like Gecko) Version/9.0.3 Safari/601.4.4 
ENTRY 018 .018. &dollar; {15}response_status={3}200
ENTRY 019 [026] &dollar; {15}response_reason={2}OK
ENTRY 020 .011. &lt; {6}server={33}HTTPd-WASD/11.0.0 OpenVMS/AXP SSL
ENTRY 021 [002] &lt; {4}date={29}Tue, 02 Feb 2016 10:40:59 GMT
ENTRY 022 .005. &lt; {13}accept-ranges={5}bytes
ENTRY 023 [008] &lt; {15}accept-encoding={13}gzip, deflate
ENTRY 024 .004. &lt; {7}expires={29}Fri, 13 Jan 1978 14:00:00 GMT
ENTRY 025 [030] &lt; {13}cache-control={18}no-cache, no-store
ENTRY 026 .028. &lt; {6}pragma={8}no-cache
ENTRY 027 .030. &lt; {12}content-type={29}text/html; charset=ISO-8859-1
ENTRY 028 [006] &lt; {14}content-length={5}15741
ENTRY 029 [019] &dollar; {15}response_header={446}HTTP/1.1 200 OK
x-user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit/601.4.4 (KHTML, like Gecko) Version/9.0.3 Safari/601.4.4
server: HTTPd-WASD/11.0.0 OpenVMS/AXP SSL
date: Tue, 02 Feb 2016 10:40:59 GMT
accept-ranges: bytes
accept-encoding: gzip, deflate
expires: Fri, 13 Jan 1978 14:00:00 GMT
cache-control: no-cache, no-store
pragma: no-cache
content-type: text/html; charset=ISO-8859-1
content-length: 15741

<span class="high italic">8&lt; snip 8&lt;</span>
</div>

<p> The first three digit number is simply the entry count in order of
insertion.  The second, either square bracketed or period delimited, is the
hash table entry.  The square brackets indicate the head of the hash table, the
periods down the collision list.  The single punctuation character is use to
indicate and differentiate the entry type.  Then are the key and
equate-separated value.  The brace enclosed numbers are the  length of the key
and value respectively.
<!-- source:0800_GLOBAL.WASDOC -->

<table class="NAVtable NAVprint"><tr>
<td><a href="javascript:window.history.back();">&#8617;&#xFE0E;</a>
<td><a href="config004.html#4.">&#8598;&#xFE0E;</a>
<td><a href="config000.html#0.">&#8593;&#xFE0E;</a>
<td><a href="config006.html#6.">&#8600;&#xFE0E;</a>
<td><a href="javascript:window.history.forward();">&#8618;&#xFE0E;</a>
</table>