~info-martin-konrad/epics-gateway/putlog : revision 165

1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

2

<html>

3

<head>

4

5

<title>Gateway Users Guide</title>

6

</head>

7

8

9

10

11

<h1 style="text-align: center">Gateway Users Guide</h1>

12

13

14

15

16

<h2 style="text-align: center">Kenneth Evans, Jr.</h2>

17

18

<h2 style="text-align: center">September 2005</h2>

19

20

<h3 style="text-align: center">Updated July 2007, Dirk Zimoch</h2>

21

22

23

24

25

Advanced Photon Source

26

Argonne National Laboratory

27

9700 South Cass Avenue

28

Argonne, IL 60439

29

</center>

30

31

32

33

34

<h2>Table of Contents</h2>

35

<ul>

36

<li><a href="#Introduction">Introduction</a>

37

<ul>

38

<li><a href="#Overview">Overview</a></li>

39

<li><a href="#History">History</a></li>

40

</ul>

41

</li>

42

<li><a href="#Starting">Starting the Gateway</a></li>

43

<li><a href="#Using">Using the Gateway</a></li>

44

<li><a href="#ErrorMessages">Error messages</a></li>

45

<li><a href="#Building">Building the Gateway</a></li>

46

<li><a href="#AccessSecurity">Access Security</a></li>

47

<li><a href="#Report">Reports</a></li>

48

<li><a href="#ServerMode">Server Mode</a></li>

49

<li><a href="#ProcessVariables">Gateway Process Variables</a></li>

50

<li><a href="#AlarmHandler">Alarm Handler</a></li>

51

<li><a href="#PutLogging">Put Logging</a></li>

52

<li><a href="#BeaconAnomalies">Beacon Anomalies and Search Requests</a></li>

53

<li><a href="#GUIInterface">GUI Interface</a></li>

54

<li><a href="#Gateway">Gateway Configurations</a>

55

<ul>

56

<li><a href="#SymmetricGateways">Symmetric Gateways</a></li>

57

<li><a href="#ReverseGateway">Reverse Gateway</a></li>

58

<li><a href="#AliasGateway">Alias Gateway</a></li>

59

</ul>

60

</li>

61

<li><a href="#ChannelAccess">Channel Access</a></li>

62

<li><a href="#Acknowledgements">Acknowledgements</a></li>

63

<li><a href="#Copyright">Copyright</a></li>

64

</ul>

65

66

<h2><a name="Introduction">Introduction</a></h2>

67

68

<h3><a name="Overview">Overview</a></h3>

69

70

The Gateway is both a <a href="#ChannelAccess">Channel Access Server</a>

71

and <a href="#ChannelAccess">Channel Access Client</a> that provides a means

72

for many clients to access a process variable while making only one

73

connection to the server that owns the process variable. It also provides

74

additional access security beyond that on the server. It thus protects

75

critical servers while providing possibly restricted access to needed process

76

variables. The Gateway typically runs on a machine with multiple network

77

cards, and the clients and the server may be on different subnets.

78

79

Previous versions of the Gateway worked with EPICS 3.13 but required a

80

special version of base to build and work correctly. The required changes

81

were never incorporated into EPICS base. The latest of these versions is

82

Gateway 1.3. The new version, starting as Gateway 2.0, only works well with

83

EPICS 3.14.6 or later and does not otherwise require a special EPICS base. It

84

also has additional features compared to Gateway 1.3. Note that even if you

85

are using EPICS 3.13 for your other applications, you can still use Gateway

86

2.x built with EPICS 3.14 as your Gateway.

87

88

For this guide we will often refer to the clients as <a

89

href="http://www.aps.anl.gov/epics/extensions/medm/index.php">MEDM</a> and

90

the server as an IOC. This is (1) to avoid confusion with the client and

91

server parts of the Gateway and (2) because MEDM and IOCs are the most

92

typical and most used client and servers and most people are familiar with

93

them. Keep in mind, however, that there are many other clients than MEDM and

94

there are other types of servers than an IOC. The Gateway is, in fact,

95

another type of server.

96

97

The following is a diagram of several MEDMs connected through the Gateway

98

to a process variable in an IOC. Without the Gateway there would be a

99

connection from each MEDM to the IOC. This uses up extra resources in the IOC

100

and causes additional traffic.

101

102

<img alt="Gateway Connections"

103

src="Gateway.Connections.gif">

104

105

In addition, these MEDMs can be restricted in their access to the process

106

variable. A typical scenario is to allow only read access. Note that the

107

MEDMs see the Gateway as just another server, and the IOCs see the Gateway as

108

just another client. The IOCs could be on a different subnet from the MEDMs,

109

and in fact, the IOCs might not even be visible to the MEDMs without the

110

Gateway. In the case where the IOCs and the MEDMs are on different subnets,

111

the Gateway would be on a machine that has two network interface cards, one

112

to the MEDM subnet and one to the IOC subnet.

113

114

At the APS the main Gateway is for people in the office building to

115

connect to the machine network with read access only. There can be many users

116

connected to popular process variables, such as the one for the beam current.

117

There is only the one Gateway connection, however, to the IOC with that

118

process variable. It is little affected by all these users and can go about

119

its primary responsibility of helping keep the accelerator running. This

120

Gateway typically has connections to on the order of 10,000-30,000 process

121

variables in on the order of 300 IOCs. In addition the APS has one Gateway

122

for each experimental team. These teams have read access to machine process

123

variables and read/write access to their own process variables. There are on

124

the order of 60 Gateways running at the APS.

125

126

In addition to connections to process variables in IOCs and other servers,

127

the Gateway, as a server, provides its own <a

128

href="#ProcessVariables">internal process variables</a>. These are used for

129

diagnostic purposes, to initiate reports, and to control the Gateway.

130

131

Internally the Gateway maintains two objects for each process variable.

132

There is a PV (Process Variable) object that handles the Gateway client

133

connections to the IOC, and there is a VC (Virtual Connection) object that

134

handles the Gateway server connections. Each VC has a list of Chan (Channel)

135

connections to the MEDMs. The PV object implements the client side of the

136

Gateway, and the VC object and its Chans implement the server side. The

137

following picture shows three typical states for these objects.

138

139

<img alt="Gateway Internals"

140

src="Gateway.Internals.gif">

141

142

In the top state there is no connection to the IOC, either because it is

143

still trying to connect or because the connection has been lost. In that case

144

there is no VC, and the MEDMs see the process variable as not existing. In

145

this case the PV object is destroyed after two minutes unless it connects.

146

The middle state is most typical. There is a connection to the IOC, and each

147

MEDM is connected through the VC. In the lower state the PV is connected to

148

the IOC, but there are no MEDMs interested in the process variable. The PV

149

object and connection to the IOC are maintained for two hours after the last

150

time they are used in case another MEDM or other client wants to use it

151

again. The other client could be a command-line program like caget, that

152

requests the value and then exits. In that case the PV object will still stay

153

around for at least two hours.

154

155

When a Channel Access Client wants to connect to a process variable, it

156

send out a series of search requests, which are UDP packets, on the network.

157

These packets are initially sent at a very fast rate with the time between

158

them doubling at each try until 100 are sent or there is an affirmative

159

reply. Each server that gets such a packet is required to determine if it has

160

the process variable. When the Gateway gets such a request, it creates an

161

unconnected PV object that itself sends a search request to the IOCs. This PV

162

starts out as Connecting, and the Gateway responds to the

163

search request as postponed. If it does not connect in a very short time, it

164

becomes Dead and the Gateway responds to subsequent search

165

requests as not having it. If it is not found by the Gateway after two

166

minutes, the PV is destroyed. If it becomes connected to an IOC, its new

167

state depends on its old state. If it was Disconnected or

168

Dead, then it becomes Inactive and the next

169

Exist Test will return that it was found. If it was

170

Connecting, postponed Exist Tests are

171

processed, and if a VC is created because an MEDM is still interested, it

172

becomes Active. Soon afterward a Chan is created, and the

173

MEDM is connected to the VC and through it to the PV. Once the PV is

174

Active or Inactive, the Gateway responds to

175

subsequent search requests as having the process variable. If the connection

176

is then lost, the VC and its Chans are destroyed, and the PV becomes

177

Disconnected.

178

179

<a href="#ProcessVariables">Internal process variables</a> in the Gateway

180

give the number of PVs in each state, and can be used to monitor its

181

behavior. In order to interpret the results, it is necessary to have an

182

understanding of these states.

183

184

PVs are either Connected or Unconnected.

185

Connected consists of either Active or

186

Inactive. Unconnected consists of

187

Connecting, Dead, or

188

Disconnected. The top state in the picture above is

189

Unconnected, but it is not clear whether it is

190

Connecting, Dead, or

191

Disconnected. The middle state is Connected

192

and Active. The bottom state is

193

Connected and Inactive.

194

<ul>

195

<li>total = connected + unconnected</li>

196

<li>connected = active + inactive</li>

197

<li>unconnected = connecting + dead + disconnected</li>

198

</ul>

199

200

Saying this another way: the PVs for which the Gateway has an established

201

client connection with an IOC are Connected. Otherwise they

202

are Unconnected. For the Connected ones, if

203

there is a connection to an MEDM, then they are Active.

204

Otherwise they are Inactive. If they are

205

Unconnected, it may because they are

206

Disconnected (meaning formerly connected),

207

Connecting, or Dead.

208

209

210

211

212

213

The Gateway handles most of the information about a process variable that

214

would be needed by most Channel Access Clients, in particular MEDM. An

215

exception is the RTYP field for records in an IOC. <a

216

href="http://www.aps.anl.gov/asd/controls/epics/EpicsDocumentation/ExtensionsManuals/MEDM/MEDM.html#PVInfoDialogBox">PvInfo

217

in MEDM</a> shows this field if directly connected to an IOC, but just shows

218

Not Available if through the Gateway. The field is the record type of the

219

process variable and is little used. It has not been deemed reasonable to add

220

the overhead to the Gateway to make it available. See the discussion under <a

221

href="#AlarmHandler">Alarm Handler</a> for more technical information on this

222

issue.

223

224

For information on obtaining the Gateway, consult the <a

225

href="http://www.aps.anl.gov/epics/index.php">EPICS Documentation</a>.

226

227

<h3><a name="History">History</a></h3>

228

229

The Gateway was originally written by Jim Kowalkowski of the APS starting

230

in early 1996. Its basic concept and structure owes to him, but it was never

231

really finished and did not work well or reliably. Janet Anderson did some

232

work on it after Jim left the APS. Kenneth Evans took it over in 1999, and

233

made it work in a usable fashion. This required making several changes to

234

EPICS base, however. These changes were never officially incorporated into

235

EPICS base, and it hence required a special version of base to build the

236

Gateway. Ralph Lange of BESSY also worked on the earlier version and took the

237

Gateway over in 2001, adding regular expressions to the process variable

238

specifications and making it work with the Alarm Handler. Kenneth Evans

239

converted it to EPICS 3.14 in mid-2002, working with Jeff Hill of LANL, the

240

person in charge of <a href="#ChannelAccess">Channel Access</a>. New

241

features, including many more internal process variables were added, and it

242

was made to run on Linux and WIN32. There were problems with the early 3.14

243

versions of Channel Access, and these were slowly resolved over the period

244

from then until late summer 2003. It now works acceptably with EPICS 3.14.6

245

or later, uses the standard version of base, uses appreciably less CPU than

246

Gateway 1.3, and has a number of new features as well as some bug fixes.

247

In 2007, some bugfixes and new features have been applied by Gasper Jansa

248

(cosylab) and Dirk Zimoch (PSI). Due to some alarm handler related bugs in

249

older versions of EPICS base, it is recommended to use EPICS 3.14.9 or

250

later.

251

252

253

<h2><a name="Starting">Starting the Gateway</a></h2>

254

255

The Gateway is started by typing the following on a command line:

256

<pre>gateway [Options]</pre>

257

258

The options are:

259

260

261

<tbody>

262

<tr>

263

<td>-debug <value></td>

264

<td>Enter a value between 0-100. 50 gives lots of information, 1 gives

265

a small amount. For developers.</td>

266

</tr>

267

<tr>

268

<td>-pvlist <filename></td>

269

<td>Name of the file with all the allowed PVs in it. There is a sample

270

file, gateway.pvlist, in the source distribution and reproduced <a

271

href="GATEWAY.pvlist">here</a>. The version in the distribution may

272

be more recent. See <a href="#AccessSecurity">Access Security</a> for

273

more information.</td>

274

</tr>

275

<tr>

276

<td>-access <filename></td>

277

<td>Name of the file with all the EPICS access security rules in it.

278

The syntax for this file is the same as that for EPICS access

279

security. See the <a href="#ChannelAccess">Application Developers

280

Guide</a> for more information on this syntax and EPICS access

281

security in general, and see <a href="#AccessSecurity">Access

282

Security</a> below for more information. There is a sample file,

283

gateway.access, in the source distribution and reproduced <a

284

href="GATEWAY.access">here</a>. The version in the distribution may

285

be more recent.</td>

286

</tr>

287

<tr>

288

289

<td>Name of file where all messages from the Gateway go, including

290

stderr and stdout. This file will be automatically renamed if the

291

Gateway is in server mode and it restarts.

292

</td>

293

</tr>

294

<tr>

295

<td>-command <filename></td>

296

<td>Name of the file where your customized Gateway command file goes.

297

The specified commands in this file are executed when a USR1 signal

298

is sent to the Gateway or the <a href="#ProcessVariables">internal

299

process variable</a>, gateway:commandFlag, is set to 1. Lines in the

300

command file may be R1, R2, R3, or AS to run reports 1-3 and reread

301

the access security file, respectively. See <a

302

href="#Report">Reports</a> below for more information. There is a

303

sample file, gateway.command, in the source distribution and

304

reproduced <a href="GATEWAY.command">here</a>. The version in the

305

distribution may be more recent</td>

306

</tr>

307

<tr>

308

<td>-putlog <filename></td>

309

<td>Name of the file where Gateway put logging goes. Put logging is

310

specified with TRAPWRITE in the access file. See the <a

311

href="#ChannelAccess">Application Developers Guide</a> under access

312

security as well as <a href="#AccessSecurity">Access Security</a> and

313

<a href="#PutLogging">Put Logging</a> below for more information.

314

This file will be automatically renamed if the Gateway is in server

315

mode and it restarts.</td>

316

</tr>

317

<tr>

318

<td>-report <filename></td>

319

<td>Name of the file where <a href="#Report">reports</a> go. The

320

reports are appended if the file exists when the reports are

321

generated. If not specified, the name is

322

gateway:report.</td>

323

</tr>

324

<tr>

325

326

<td>Directory where the Gateway looks for its input files and writes

327

its output files. Setting this is equivalent to changing to that

328

directory before starting the Gateway. Setting the environment

329

variable GATEWAY_HOME also accomplishes the same result.</td>

330

</tr>

331

<tr>

332

333

<td>IP address where the Gateway server listens for process variable

334

requests. Sets the environment variable EPICS_CAS_INTF_ADDR.</td>

335

</tr>

336

<tr>

337

<td>-signore <ip-address-list></td>

338

<td>List of IP address that the Gateway server ignores. Sets the

339

environment variable EPICS_CAS_IGNORE_ADDR_LIST.</td>

340

</tr>

341

<tr>

342

343

<td>List of IP addresses that the Gateway client uses to find the real

344

process variables. See the <a href="#ChannelAccess">Channel Access

345

Reference Manual</a> for more information. Sets the environment

346

variables EPICS_CA_AUTO_LIST=NO and EPICS_CA_ADDR_LIST.</td>

347

</tr>

348

<tr>

349

<td>-sport <port></td>

350

<td>The port which the Gateway server uses to listen for process

351

variable requests. The default is 5064. Sets the environment variable

352

EPICS_CAS_SERVER_PORT.</td>

353

</tr>

354

<tr>

355

<td>-cport <port></td>

356

<td>The port which the Gateway client uses to find the real process

357

variables. Sets the environment variable EPICS_CA_SERVER_PORT. Be

358

aware that if you specify -cport and do not specify -sport, then the

359

server port will also be the same as what you specify for -cport.

360

This is a Channel Access feature. To avoid it, specify -sport.</td>

361

</tr>

362

<tr>

363

<td>-connect_timeout <sec></td>

364

<td>The amount of time in seconds that the Gateway will allow a process

365

variable search to continue before marking the process variable as

366

being Dead. The default is 1.</td>

367

</tr>

368

<tr>

369

<td>-inactive_timeout <sec></td>

370

<td>The amount of time in seconds that the Gateway will hold the real

371

connection to an Inactive process variable. The

372

default is 7200 (2 hours).</td>

373

</tr>

374

<tr>

375

<td>-dead_timeout <sec></td>

376

<td>The amount of time in seconds that the Gateway will continue to

377

look for process variables that are Connecting to

378

the IOCs that the Gateway is using. The default is 120 (2 min).</td>

379

</tr>

380

<tr>

381

<td>-disconnect_timeout <sec></td>

382

<td>The amount of time in seconds that the Gateway will hold

383

Disconnected process variables (those that were

384

connected but have been disconnected). The default is 7200 (2

385

hours).</td>

386

</tr>

387

<tr>

388

<td>-reconnect_inhibit <sec></td>

389

<td>The minimum amount of time in seconds after the last beacon anomaly

390

sequence before generating a new one. The Gateway generates a beacon

391

anomaly sequence when process variables from the IOCs reconnect and

392

when it rereads access security. Thus causes MEDMs to reissue search

393

requests for unconnected PVs. Used to limit the beacon sequences, and

394

hence the search requests. Search requests last for about 8 min., so

395

it is not necessary to reissue beacon anomalies much more frequently

396

than 8 min. The default is 300 (5 minutes).</td>

397

</tr>

398

<tr>

399

<td>-server</td>

400

<td>Start in server mode. Start a daemon that watches the Gateway and

401

automatically restarts it if it dies. Not available on WIN32. See <a

402

href="#ServerMode">Server Mode</a>.</td>

403

</tr>

404

<tr>

405

406

<td>Event mask that is used for connections to the IOCs. Use any

407

combination of v (value), a (alarm), l (log). The default is va

408

(forward value and alarm change events). Also see option -archive.</td>

409

</tr>

410

<tr>

411

<td>-prefix <string></td>

412

<td>Set the prefix for the Gateway <a href="#ProcessVariables">internal

413

process variables</a>. Defaults to the hostname on which the Gateway

414

is running.</td>

415

</tr>

416

<tr>

417

418

<td>Run the Gateway server as this user id number. The Gateway does a

419

setuid(2) to this uid. Not available on WIN32.</td>

420

</tr>

421

<tr>

422

423

<td>Run the Gateway server as this group id number. The Gateway does a

424

setgid(2) to this uid. Not available on WIN32.</td>

425

</tr>

426

<tr>

427

<td>-archive</td>

428

<td>Use separate archive monitors (which honor ADEL instead of MDEL)

429

when archive client connects. This is the preferred method (in

430

opposite to -mask) when the gateway should be used by archivers and

431

"normal" clients (medm) at the same time.</td>

432

</tr>

433

<tr>

434

<td>-no_cache</td>

435

<td>Do not use cached (monitored) values when a client does ca_get.

436

This results in higher network traffic to the IOC but returns always

437

the current value, even if no monitor event had been send

438

(e.g. because of a MDEL). This also solves problems with record

439

fields like HOPR or EGU if they are modified during run-time.

440

</td>

441

</tbody>

442

</table>

443

444

445

446

A typical command line is:

447

<pre>% gateway -log gateway.log -cip 164.54.3.255 -sip 164.54.188.65 -server -archive -no_cache</pre>

448

449

For the command-line options that set environment variables, an

450

alternative would be to set them yourself before starting the Gateway instead

451

of using the option.

452

453

With EPICS 3.13, there should be no more than one portable server, such as

454

a Gateway, running on a workstation. The reason is that there is not

455

sufficient information in the beacons to distinguish among servers on the

456

same host. Clients such as MEDM must treat their beacons as one set of beacon

457

signals and will see sum and difference frequencies. They will likely

458

interpret this as an IOC coming up and will continuously reissue their

459

outstanding search requests. As a result, if the Gateway is one of two

460

portable servers on the same host, it will be causing a problem. Two servers

461

on the same host should not be a problem with 3.14 servers. It is not clear

462

what will happen with a mixture of 3.13 and 3.14 servers on the same

463

workstation. That situation should be avoided.

464

465

The Gateway makes two files, gateway.killer and

466

gateway.restart, when it starts. The file

467

gateway.killer contains a summary of the settings used, as

468

well as commands to kill the current Gateway, kill the server if in server

469

mode, execute the <a href="#Report">commands file</a>, and execute the <a

470

href="#Report">Process Variable Report</a>. It is a valid shell script, and

471

the only line not commented is the one which kills the server in server mode

472

or the current Gateway otherwise. Consequently, it can be run to kill the

473

server in server mode or the current Gateway otherwise. The other command

474

lines can be pasted to a shell to do the other actions. The file

475

gateway.restart can be used to kill the current Gateway, whether in

476

server mode or not. These files and features are not available on WIN32.

477

478

The Gateway can also create a file named gateway.reserve.

479

It does this to get around a problem that a process can only open files with

480

file descriptors (FDs) below a certain limit (256 on Solaris). If there are

481

connections to more than roughly this number of IOCs, not uncommon in a

482

production environment, there is no FD available to reread the <a

483

href="#AccessSecurity">access security</a> and <a href="#Report">command</a>

484

files. The Gateway gets around this by reserving a FD pointing to

485

gateway.reserve. Do not delete

486

gateway.reserve. Also note that if reading the access

487

security fails for this or any other reason, the access security will go to

488

the default, not what it was before the failure.

489

490

The number of threads on Linux is determined by the maximum user space,

491

about half of the 32-bit address space or about 2 GB. The maximum number of

492

threads is thus 2 GB divided by the stacksize (typically 10240 KB) giving

493

about 204 threads in the typical case. Channel Access uses two threads for

494

each IOC connection, one for receive and one for send. This limits the

495

Gateway from connecting to more than about 100 IOCs. If the stacksize were

496

decreased to say, 4096 KB (ulimit -s 4096), then about 256 IOCs would be

497

allowed. The APS Linux Gateway currently uses this number. Starting with Base

498

3.14.7, EPICS allocates memory for threads more efficiently, and you should

499

not have to change the stacksize.

500

501

If arrays larger then 16 KB should be passed through the gateway, the

502

environment variable EPICS_CA_MAX_ARRAY_BYTES must be set to a sufficiently

503

high value before the gateway is started. Set it at least to the maximum value

504

used on any IOC.

505

506

<h2><a name="Using">Using the Gateway</a></h2>

507

508

To use the Gateway as your process variable server, it is usually only

509

necessary to set your EPICS_CA_ADDR_LIST environment variable to the address

510

used for the -sip <a href="#Starting">command-line</a> option when the

511

Gateway was started. If want to use more than one server, add them all to the

512

list for EPICS_CA_ADDR_LIST, separated by spaces. You probably also want to

513

set EPICS_CA_AUTO_ADDR_LIST to NO to prevent also searching the local network

514

for servers. You would certainly do this if there are IOCs on the local

515

network that might have process variables with the same names as ones the

516

Gateway would find. They would then be found from two servers, and your EPICS

517

application would likely complain. If the Gateway is using a non-standard

518

port, you need to set EPICS_CA_SERVER_PORT to the number used with -sport

519

when the Gateway was started. Then just run your EPICS application, for

520

example, MEDM.

521

522

To stop the Gateway, use the gateway.killer file

523

(described under <a href="#Starting">Starting the Gateway</a>), set the

524

gateway.quitFlag or gateway.quitServer flag

525

(described under <a href="#ProcessVariables">Gateway Process Variables</a>),

526

or kill it in the usual way for your operating system. It may take a while to

527

completely shut down. This is owing to EPICS cleanup processes that run after

528

the program has officially exited. These processes may also print error

529

messages after the Gateway prints its termination message just before calling

530

exit. It is a good idea to check that the Gateway has truly shut down. This

531

behavior may be corrected in future releases of base.

532

533

534

535

<h2><a name="ErrorMessages">Error messages</a></h2>

536

537

The Gateway gets error messages from several places, including internally,

538

the Channel Access Server library, and the Channel Access Client library.

539

These errors typically appear in the log. The Gateway internal messages

540

usually have a timestamp. Messages from the Channel Access Server library are

541

typically sent to the EPICS Errlog facility and are received by the Gateway,

542

often with different lines of the message being received separately. These

543

messages typically do not have a timestamp, and the Gateway puts a line in

544

the log with a timestamp when it thinks the message is complete. This line

545

will say "!!! Errlog message received (message is above)". You must try to

546

decide what lines above this line comprise the message. The problem is

547

compounded by the fact that other kinds of messages may be interspersed

548

between the lines for the Errlog message. The Channel Access Server library

549

can also write messages directly. The Channel Access Client library can use

550

the Errlog facility or send exception messages to the Gateway. The Errlog

551

messages are handled as described. The exception messages are printed with as

552

much additional information as is available and will start with a line with a

553

timestamp saying "gateServer::exCB: Channel Access Exception:". Common

554

exception messages, such as "Virtual circuit unresponsive" and "Virtual

555

circuit disconnect" only print a single, timestamped line without the

556

additional information. In most cases the Gateway prints a line with a

557

timestamp saying how it was terminated. If the process is killed with SIGKILL

558

(-9) or the machine is rebooted, this line has no chance to appear. In all

559

cases the Gateway attempts to timestamp messages as timing is often important

560

in diagnosing problems.

561

562

<h2><a name="Building">Building the Gateway</a></h2>

563

564

The Gateway uses 3.14 makefiles as it can only be built with 3.14. To

565

build it you need to:

566

<ol>

567

<li>Obtain base and put it at the same directory level as extensions. Use

568

at least base 3.14.</li>

569

<li>Do a make in base to build base.</li>

570

<li>Obtain extensions/configure.</li>

571

<li>Change extensions/configure/RELEASE so EPICS_BASE points to your

572

base.</li>

573

<li>Do a make in extensions/config.</li>

574

<li>Make sure that either GNU or Perl regular expressions are

575

installed on your system. If neither is available, obtain the GNU

576

Regex extension and build it in extensions/src/gnuregex.</li>

577

<li>Obtain the Gateway directory and put it under

578

extensions/src/gateway.</li>

579

<li>Check the settings in extensions/src/gateway/Makefile.</li>

580

<li>Do a make in extensions/src/gateway.</li>

581

</ol>

582

583

See your version of base for more information on the EPICS build system.

584

The Gateway can also be built with 3.13 makefiles, but you would have to

585

create Makefile and Makefile.Host yourself to do that.

586

587

<h2><a name="AccessSecurity">Access Security</a></h2>

588

589

The Gateway applies access security in addition to any access security

590

that may be implemented in the IOCs or other servers to which it connects. It

591

supplements but cannot override IOC access security. The access security is

592

specified in two files, gateway.pvlist and

593

gateway.access, by default. See -pvlist and -access on the<a

594

href="#Starting"> command line</a>. The first file,

595

gateway.pvlist, specifies what process variable name

596

patterns are allowed and denied, and is described in more detail below. The

597

second, gateway.access, specifies the access security rules.

598

These two files are read at startup.

599

600

The access security can be changed on demand by setting the internal

601

process variable gateway:newAsFlag (see<a

602

href="#ProcessVariables"> Gateway Process Variables</a>) or by using the

603

command file (see <a href="#Report">Reports</a>). This causes the two files

604

to be reread and the access security to be changed accordingly. After

605

rereading access security, the Gateway generates a beacon anomaly, which will

606

cause MEDMs to reissue search requests for unfound PVs.

607

608

Note that if reading the access security fails, the access security will

609

go to the default, not what it was before the failure.

610

611

The access security rules specified in gateway.access are

612

the same as used for access security in IOCs. In fact, both IOCs and the

613

Gateway use much of the same access-security code. These rules and the

614

concepts can be complicated and will not be reproduced in this document. See

615

the<a href="#ChannelAccess"> Application Developers Guide</a> for more

616

information. It can be noted that user names are case sensitive and host

617

names are not. WIN32 may use a different case than UNIX for the same account.

618

In this case user names must be entered with both versions. There is a sample

619

file, gateway.access, in the source distribution and reproduced <a

620

href="GATEWAY.access">here</a> to get you started. The version in the

621

distribution may be more recent.

622

623

The pvlist file is specific to the Gateway. Its function is to specify

624

what process variable name patterns are allowed or denied and to optionally

625

associate patterns with access security groups and security levels in the

626

access file. The patterns are either Perl compatible regular expressions

627

(PCRE) or GNU-style regular expressions, depending on the USE_PCRE variable

628

in Makefile. (See a UNIX book for more information about regular expressions.)

629

In addition, inverted regular experessions (starting with !) are supported

630

depending on the USE_NEG_REGEXP variable in Makefile. For compatibility

631

with earlier versions of the gateway, PCRE and inverted regular expressions

632

are disable by default. There is a sample file,

633

gateway.pvlist, in the source distribution and reproduced <a

634

href="GATEWAY.pvlist">here</a> to get you started. The version in the

635

distribution may be more recent. Directions for this file are in the sample

636

pvlist file as well as here.

637

638

The lines in the pvlist file are of the following four forms:

639

<ol>

640

<li>EVALUATION ORDER <eval-order></li>

641

642

<li><pv-name-pattern> ALIAS <real-pv-name> [<asg>

643

[<asl>]]</li>

644

<li><pv-name-pattern> ALLOW [<asg> [<asl>]]</li>

645

</ol>

646

647

where:

648

<ul>

649

<li><eval-order> is DENY, ALLOW or ALLOW, DENY</li>

650

<li><pv-name-pattern> is a regular expression that matches process

651

variable names.</li>

652

<li><host> is an unqualified host name, e.g. hydra.</li>

653

<li><real-pv-name> is a substitution pattern that specifies the real

654

process variable name. Occurrences of \1 ... \9 in <real-pv-name>

655

are replaced by matched sub-expressions in the

656

<pv-name-pattern>.</li>

657

<li><asg> is an access security group as specified in the access

658

file. [The default group is DEFAULT.]</li>

659

<li><asl> is the access security level (0 or 1). These numbers

660

pertain to the settings for particular fields in a record in an IOC.

661

Permission for level 1 implies permission for level 0. See the<a

662

href="#ChannelAccess"> Application Developers Guide</a> for more

663

information on access security group and access security level.</li>

664

</ul>

665

666

In this version of the gateway, DENY FROM is enabled by default again.

667

It can be useful if access from certain hosts should be denied only for some

668

channels. If access should be denied for all channels, it is more efficient

669

to use -signore. DENY FROM can be disabled with the USE_DENY_FROM variable

670

in Makefile.

671

672

EVALUATION ORDER

673

674

This will set the evaluation order that is used when a client requests a

675

process variable. Setting this to "DENY, ALLOW" will allow access to a

676

process variable name that matches both a DENY and an ALLOW pattern. "ALLOW,

677

DENY" will make a DENY override an ALLOW for the same variable. (This is the

678

default.)

679

680

If DENY FROM is enabled, then matching DENY FROM host-name patterns will

681

always override matching ALLOW process-variable-name patterns.

682

683

Stated another way, the Gateway keeps three lists for: DENY FROM (if

684

enabled), DENY, and ALLOW. The DENY FROM list is searched first, and if the

685

host name is found, access is disallowed. If the order is ALLOW, DENY, the

686

DENY list is searched, and if the process variable name is found, access is

687

disallowed. Then the ALLOW list is searched, and if the name is found, access

688

is allowed, otherwise it is disallowed. Disallowed means the Gateway returns

689

that it does not have the process variable when the Exist

690

Test is called. In addition, for safety, it will not create a

691

connection to an MEDM.

692

693

The lines in the pvlist file are read from bottom to top. The first rule

694

in each list that matches is used, so the most general rules should be placed

695

first.

696

697

DENY / DENY FROM

698

699

The Gateway will ignore requests for any process variable that matches the

700

DENY pattern, depending on the EVALUATION ORDER and whether there is also an

701

ALLOW rule that matches. This can be used to block the Gateway from

702

responding to groups of process variables. DENY FROM will block the process

703

variables only for the given hosts. This can be useful to prevent loops

704

caused by forwarding to other Gateways. However, the host name lookup for

705

each Exist Test can take considerable time. Moreover, the

706

same result can be accomplished via the -signore <a

707

href="#Starting">command-line</a> option. See the <a

708

href="#SymmetricGateways">symmetric Gateway</a> configuration below for an

709

example.

710

711

ALIAS

712

713

This defines a process variable alias and allows it as a pattern for names

714

which the Gateway should serve. For process variable names that match

715

<pv-name-pattern>, the Gateway translates the name into a real process

716

variable name and uses the real name as if it had been the one specified. The

717

<real-pv-name> may contain the special escape sequences \1 ... \9 which

718

will be replaced by the nth subexpression matched. See a UNIX book on regular

719

expressions for more information. There is an example in the<a

720

href="GATEWAY.pvlist"> sample pvlist file</a>. Access security rules to be

721

used for process variables matched by this pattern may be specified. If not

722

specified, the defaults are the DEFAULT group and level 1. Apart from

723

specifying an alias, this rule is functionally the same as ALLOW. Note that a

724

PV can only belong to one access group and access level. If you specify

725

access to a real PV via several different ALIAS or ALLOW rules that assign

726

different groups or levels to the PV, then which of these groups and levels

727

is used is undefined.

728

729

ALLOW

730

731

This is used to declare process variable names which the Gateway should

732

serve. Access security rules to be used for process variables matched by this

733

pattern may be specified. If not specified, the defaults are the DEFAULT

734

group and level 1.

735

736

Note

737

<ol>

738

<li>Commands are not case sensitive.</li>

739

<li>Patterns use GNU-style regular expressions. (See a UNIX book for

740

information on regular expressions.)</li>

741

<li>Any process variable not included in an ALLOW command is not allowed

742

access.</li>

743

<li>If no pvlist file is specified on the command line, a default rule ".*

744

ALLOW" will be created to handle all process variables.</li>

745

<li>The patterns are matched in reverse order; that is, you should always

746

specify general rules before specific rules.</li>

747

</ol>

748

749

<h2><a name="PutLogging">Put Logging</a></h2>

750

751

It is possible to log whenever someone writes to a process variable. (A

752

write is sometimes called a "put" and a read is called a "get".) To do this

753

you need to specify -putlog on the<a href="#Starting"> command line</a> when

754

the Gateway is started and specify a filename for the put logging. There

755

needs to be an access security group in the gateway.access

756

file that has a rule with WRITE and TRAPWRITE specified, for example,

757

"RULE(1,WRITE,TRAPWRITE)". (The security level could also be 0.) Then

758

whenever there is a write (or put) to any process variable in that group, it

759

will be logged in the specified putlog file. As with the log file, this file

760

will be automatically renamed whenever the Gateway restarts. An example may

761

be found in the<a href="GATEWAY.access"> sample access file</a>, where writes

762

are logged for process variables that belong to the GatewayAdmin group. Using

763

the <a href="GATEWAY.pvlist">sample pvlist file</a>, these would be those

764

that fit the pattern "gateway:*Flag".

765

766

<h2><a name="BeaconAnomalies">Beacon Anomalies and Search Requests</a></h2>

767

768

A server sends beacons, which are broadcast UDP packets, at regular

769

intervals, EPICS_CA_BEACON_PERIOD, 15 s by default. The clients, such as

770

MEDM, monitor these heartbeats. When there is a beacon anomaly, defined as

771

anything that is different from this regular pattern, the clients reissue

772

search requests for their unconnected PVs.

773

774

A client sends search requests when it wants to connect to a process

775

variable. A search request is a series of 100 UDP packets sent at

776

increasingly longer intervals. It takes approximately 8 min. to complete the

777

sequence. In most cases a server responds on the first or second packet; the

778

connection process between the server and the client begins; and the search

779

sequence ends. However for those PVs that are not found, the potential for a

780

connection to happen exists for approximately 8 min., as long as the packets

781

are still going out.

782

783

When client gets a hangup message from the server, it closes the TCP

784

connection, the process variable is marked as disconnected (MEDM screens turn

785

white), and search requests are reissued. In 3.13 when a client has no

786

communication from the server for EPICS_CA_CONN_TMO seconds (15 s by

787

default), it sends an "are you there" message to the server. If there is no

788

reply in 5 sec, it closes the TCP connection, the process variable is marked

789

as disconnected, and search requests are reissued, the same as for a hangup.

790

In 3.14, it marks the connection as disconnected, but does not close the TCP

791

connection nor reissue beacons. The client may get a "Virtual circuit

792

unresponsive" message. This is in part to prevent search-request storms under

793

bad network conditions.

794

795

When a server, including the Gateway comes up, it intentionally broadcasts

796

an irregular pattern for a short time (a particular form of beacon anomaly)

797

so the clients will know a new server is online and reissue their outstanding

798

search requests in case it might have those PVs. The Gateway also broadcasts

799

this irregular pattern when a PV beomes connected again after having been

800

disconnected and also when <a href="#AccessSecurity">access security</a> is

801

reread. This is so the MEDMs will know to try to reconnect.

802

803

For security reasons some network administrators will not allow UDP

804

broadcasts to cross subnet boundaries. If this is the case, then when the

805

MEDM is on a different subnet than the Gateway, it will not see beacons at

806

all and will not be able to tell if the Gateway has come up, This is a common

807

case in large installations. Owing to the length of the search request

808

sequence, if a server such as the Gateway goes down and comes back up within

809

approximately 8 min,. the MEDM will reconnect. Otherwise, it will not, unless

810

something else happens to make it reissue its searches. One such thing is to

811

try to connect to a new PV. This causes a client to reissue outstanding

812

searches along with the search for the new one. The latest versions of <a

813

href="http://www.aps.anl.gov/epics/extensions/medm/index.php"> MEDM</a> and

814

<a

815

href="http://www.aps.anl.gov/epics/extensions/StripTool/index.php">StripTool</a>

816

have a button to try to reconnect. In any event, Gateway administrators

817

should be careful to not have a long delay between killing and restarting a

818

Gateway if possible.

819

820

<h2><a name="Report">Reports</a></h2>

821

822

The Gateway prints three kinds of reports: (1) the Virtual Connection

823

Report, which includes all MEDM or other client connections to all process

824

variables; (2) the Process Variable Report, which includes all process

825

variables grouped by state; and (3) the Access Security Report, which

826

includes the allowed and denied process-variable patterns from the pvlist

827

file, gateway.pvlist, by default. The Gateway prints its

828

reports to the report file, gateway.report, by default,

829

appending them if the file already exists. These reports can be long.

830

831

The reports can be initiated by setting the associated <a

832

href="#ProcessVariables">internal process variable</a>, for example,

833

gateway:report1Flag, to 1. They can also be initiated by

834

sending a USR1 signal to the Gateway. (Use "kill -USR1

835

<gateway-pid>".). This causes the command file,

836

gateway.command, by default, to be read and the specified

837

reports executed. The command file can be modified to do any combination of

838

the three reports, as well as to reread the access security files. See the

839

-command <a href="#Starting">command-line option</a> for more details and an

840

example. The Process Variable Report can be executed by sending a USR2

841

signal. (Use "kill -USR2 <gateway-pid>".) The Gateway makes a file,

842

gateway.killer, when it starts. The commands and the correct

843

pids are printed in that file, so you can look at it to get the appropriate

844

command lines. Signals and the gateway.killer file are not

845

available on WIN32.

846

847

<h2><a name="ServerMode">Server Mode</a></h2>

848

849

The Gateway can be operated in server mode by specifying -server on the

850

command line. In this mode a server process is started that in turn starts

851

the regular Gateway process and then watches it and automatically restarts it

852

if it dies. Using this mode the Gateway can recover from crashes. The running

853

Gateway can effectively be reset by killing it via the

854

gateway:quitFlag process variable, by running

855

gateway.restart, or by killing the process in some other

856

way. When any of these methods is used or the Gateway crashes, a new instance

857

of the Gateway is started. The server process itself can be killed by setting

858

the gateway:quitServerFlag, by running

859

gateway.killer, or by otherwise killing the server process.

860

Then no more regular Gateway processes will be automatically started.

861

862

In order to avoid runaway creation of processes, there can only be ten

863

restarts in any ten-minute interval. If the number of restarts in this

864

interval exceeds this limit, the server will be stopped and no more processes

865

will be created.

866

867

This feature is not available on WIN32.

868

869

<h2><a name="ProcessVariables">Gateway Process Variables</a></h2>

870

871

The Gateway publishes several process variables, allowing you to control

872

it and monitor it. By default these have a prefix, which is the name of the

873

host machine, but this can be changed by -prefix in the<a href="#Starting">

874

command-line options</a>. Here, we will use the prefix "gateway". See the <a

875

href="#Introduction">Introduction</a> for a more detailed description of the

876

states and concepts.

877

878

The Gateway internal process variables are not record based as in an IOC.

879

They do have a DESC field, however. This avoids delays when using PvInfo in<a

880

href="http://www.aps.anl.gov/epics/extensions/medm/index.php"> MEDM</a> and

881

allows <a

882

href="http://www.aps.anl.gov/epics/extensions/StripTool/index.php">StripTool</a>

883

to put a description in the legend. In older versions of the Gateway, the

884

internal process variables used a dot as a separater rather than a colon.

885

When the DESC field was added, they were changed to use a colon. This makes

886

them more consistent with records in IOCs, and allows MEDM and StripTool to

887

properly determine the name for the DESC field. The sample <a

888

href="GATEWAY.pvlist">GATEWAY.pvlist</a> file shows how to set aliases if you

889

want to use the old names. The old names will cause MEDM and StripTool to not

890

correctly form the name for the DESC field, however. This will cause delays

891

for PvInfo in MEDM, and StripTool will not display the descriptions in the

892

legend.

893

894

gateway:vctotal

895

896

This is the total number of VC objects and should be the same as

897

gateway:active, except for short, transient

898

situations.

899

900

gateway:pvtotal

901

902

This is the number of PV objects.

903

904

gateway:connected

905

906

This is the number of connected PV objects, that is, process variables for

907

which the Gateway has a working connection to the IOC. The connections may be

908

Active or Inactive. In earlier versions of

909

the Gateway, this was named gateway:alive.

910

911

gateway:active

912

913

This is the number of Active connections. The connection

914

is Active if an MEDM is attached to the Gateway and using

915

the process variable

916

917

gateway:inactive

918

919

This is the number of Inactive connections. The

920

connection is Inactive if no MEDM connected to the Gateway

921

is using it.

922

923

gateway:unconnected

924

925

This is the number of PV objects which are Connecting,

926

Dead, or Disconnected. There is no working

927

connection to an IOC but the PV object is still around. There is no VC

928

object.

929

930

gateway:connecting

931

932

This is the number of PV objects which are Connnecting,

933

that is, which have just been created and are trying to connect to an IOC.

934

935

gateway:disconnected

936

937

This is the number of PV objects which are Disconnected,

938

that is, which were formerly connected but have lost the connection.

939

940

gateway:dead

941

942

This is the number of PV objects which are Dead, that is,

943

which did not connect and are scheduled for removal.

944

945

gateway:fd

946

947

This is the number of file descriptors in use by the gateway. This process

948

variable will only be available if registering file descriptors is enabled in

949

the Gateway when it is built. Not registering them appears to significantly

950

decrease the CPU usage, so this process variable will probably not be

951

available. It requires a special switch to be set when the Gateway is

952

built.

953

954

gateway:clientEventRate

955

956

This is the rate in Hz at which client events are happening. Client events

957

include such things as attempted read and writes, connection changes, value

958

changes, and access rights changes. They relate to communication from the

959

IOC.

960

961

gateway:clientPostRate

962

963

This is the rate in Hz at which events are posted from the VC object to

964

CAS and hence to the MEDMs. It is independent of the number of MEDMs

965

(providing there is at least one). It tends to be similar to the

966

clientEventRate; but only value changes cause post events. The other events

967

do not contribute.

968

969

In earlier versions of the Gateway this was named

970

gateway:postEventRate.

971

972

gateway:existTestRate

973

974

This is the rate in Hz at which the Gateway receives search requests. For

975

each search request, it has to do an Exist Test to see if it

976

has the process variable or not. If it is not already connected to the

977

process variable, it creates a PV object which itself initiates a series of

978

search requests to the IOCs. See the <a href="#Introduction">Introduction</a>

979

for more information on search requests. Exist Tests put a

980

load on the Gateway. For process variables that do not exist, there can be

981

many unsuccessful Exist Tests. See <a

982

href="http://www.aps.anl.gov/epics/extensions/caSnooper/index.php">CaSnooper</a>

983

for a tool to monitor Exist Tests.

984

985

gateway:loopRate

986

987

This is the rate in Hz at which the Gateway executes its main loop. The

988

main loop consists of a call to CAS followed by a call to CAC followed by

989

Gateway housekeeping routines. The call to CAS lasts for 10 ms unless there

990

is activity on a file descriptor (in which case it returns early) or if it

991

takes longer than that to process its callbacks (in which case it returns

992

late). The call to CAC takes as long as it takes to do the work required. The

993

Gateway housekeeping typically uses comparatively little time. As the Gateway

994

becomes loaded down, the calls to CAS take longer and so do the calls to CAC

995

until eventually all the available CPU time is used. As the load increases,

996

the loopRate tends to decrease. However, no load can have a lower loop rate

997

than with some load because the call to CAS waits the whole 10 ms. It is a

998

rule of thumb that CAC should be called at least every 100 ms. By examining

999

the loopRate you can tell if this is happening. That is, it should remain

1000

above 10 Hz.

1001

1002

gateway:cpuFract

1003

1004

This is the fraction of the available CPU time that is being used by the

1005

Gateway; that is, the CPU time divided by the elapsed time. It is a good

1006

monitor of the load on the Gateway. On WIN32 the cpuFract is always 1 and not

1007

useful. This is owing to their implementation of the clock() function. On

1008

Linux, threads are separate processes, and the CPU time for them is not

1009

included, only that for the main process. This is because clock() on Linux

1010

returns only the CPU time for the process that called it. If there is more

1011

than one processor, the cpuFract could exceed unity. Note that Top on Linux

1012

shows the CPU time divided by the number of processors and optionally lists

1013

all threads separately. Thus, on Linux, the Gateway cpuFract should agree

1014

with the Top value for the main Gateway process multiplied by the number of

1015

processors. You can use Top to monitor the CPU time for all the Gateway

1016

processes if you need that.

1017

1018

gateway:load

1019

1020

This is the load average for the machine on which the Gateway is running.

1021

The load average is the number of processes in the system run queue averaged

1022

over one minute. It is implemented by the getloadavg() function, and you can

1023

look at the man page for more information. It is the same as the process

1024

variable with the same name in IOCs. It is another way to monitor the load.

1025

On WIN32 it is always zero and not useful.

1026

1027

gateway:serverEventRate

1028

1029

This is the rate in Hz at which CAS processes events. It tends to be the

1030

clientEventRate multiplied by the number of MEDMs looking at the process

1031

variable.

1032

1033

gateway:serverPostRate

1034

1035

This is the rate in Hz at which events are posted to CAS. If the Gateway

1036

is keeping up, this will be very close to the serverEventRate. If not, it

1037

will be higher and all posted events will not have been processed.

1038

1039

gateway:commandFlag

1040

1041

Writing a 1 to this process variable causes the command file to be

1042

processed. The process variable is reset to 0 after the Command File is

1043

processed. See the description of <a href="#Starting">command-line</a>

1044

arguments and the <a href="#Report">Reports</a> section for a description of

1045

the command file.

1046

1047

gateway:report1Flag

1048

1049

Writing a 1 to this process variable causes Report 1 to be appended to the

1050

report file. Report 1 is the <a href="#Report">VC Report</a>.The process

1051

variable is reset to 0 afterward.

1052

1053

gateway:report2Flag

1054

1055

Writing a 1 to this process variable causes Report 2 to be appended to the

1056

report file. Report 2 is the <a href="#Report">PV Report</a>.The process

1057

variable is reset to 0 afterward.

1058

1059

gateway:report3Flag

1060

1061

Writing a 1 to this process variable causes Report 3 to be appended to the

1062

report file. Report 3 is the <a href="#Report">Access Security Report</a>.

1063

The process variable is reset to 0 afterward.

1064

1065

gateway:newAsFlag

1066

1067

Writing a 1 to this process variable causes the access security files, by

1068

default gateway.access and gateway.pvlist,

1069

to be reread. The process variable is reset to 0 afterward. There is

1070

currently a problem on some platforms that files can only be opened using

1071

file descriptors 0 to 255. If there are many CA socket connections, there may

1072

not be a file descriptor in this range available. In that case the access

1073

security file will not be read and an error will appear in the log. There is

1074

a workaround in the Gateway for this problem for Solaris.

1075

1076

gateway:quitFlag

1077

1078

Writing a 1 to this process variable causes the Gateway process to exit.

1079

If the Gateway is in server mode, it will be restarted as a new process. In

1080

that case it functions more as a reset.

1081

1082

gateway:quitServerFlag

1083

1084

Writing a 1 to this process variable causes the Gateway server process to

1085

end, also ending the current gateway. No more Gateways will be started by the

1086

current server. If the Gateway is not in server mode, it has the same effect

1087

as gateway:quitFlag.

1088

1089

<h2><a name="AlarmHandler">Alarm Handler</a></h2>

1090

1091

The Alarm Handler works through the Gateway. The following discussion is

1092

for those who understand Channel Access in more depth: For most process

1093

variables the Gateway can get all of its information in a single DBR_TIME_xxx

1094

structure, for example, DBR_TIME_DOUBLE, where xxx is the native type of the

1095

process variable. These structures are defined in db_access.h. The Gateway

1096

establishes an event handler for this structure and gets notified when it

1097

changes and modifies it when it needs to be changed. There is only one

1098

structure per process variable. This structure does not contain all the

1099

information needed by the Alarm Handler, so the Gateway need to keep track of

1100

another structure, DBR_STSACK_STRING. This is only done when needed. A

1101

related issue is that the Gateway does not handle the RTYP field in a process

1102

variable from an IOC. To do this it would have to handle DBR_CLASS_NAME. Each

1103

structure the Gateway needs to handle adds to its overhead.

1104

1105

<h2><a name="GUIInterface">GUI Interface</a></h2>

1106

1107

Owing to its <a href="#ProcessVariables">published internal process

1108

variables</a>, you can monitor and control the Gateway via MEDM or another

1109

tool. You can set the writable internal process variables (if you have

1110

access) and cause the Gateway to print reports, reread the access security

1111

file, or quit. This is an example MEDM screen:

1112

1113

1114

1115

You could also add a Shell Command button to run a script to start the

1116

Gateway. The MEDM ADL file for this screen is included in the Gateway

1117

distribution as hydraStats.adl. Typically the Exec buttons operate so fast

1118

that you will not see the value change from 0, and the Cancel button is of

1119

little use. However, the chain of events is that the Exec button sets the

1120

process variable to 1, the Gateway notices this during the cleanup phase of

1121

the main loop, the appropriate action is executed, and the process variable

1122

is reset to zero.

1123

1124

It is convenient to monitor and possibly record the state of the Gateway

1125

using <a

1126

href="http://www.aps.anl.gov/epics/extensions/StripTool/index.php">StripTool.</a>

1127

You could, of course, use any other EPICS monitoring tool of your choice.

1128

This is an example of using StripTool:

1129

1130

1131

1132

The StripTool configuration file for this image is included in the Gateway

1133

distribution as hydra.rate.stp. Note that for the example shown, the cpuFract

1134

is low, the loop rate is high, and the postRate's and eventRate's are nearly

1135

equal, indicating the Gateway is healthy.

1136

1137

<a name="APSGatewaysScreen">This is a screen that shows the status of all

1138

of the APS Gateways:</a>

1139

1140

<img alt="GatewayOverview.adl"

1141

src="GatewayOverview.adl.Reduced.jpg">

1142

1143

(<a href="GatewayOverview.adl.gif">Click here for full-size image</a>)

1144

1145

The values for inactive and dead are not being used because these Gateways

1146

are mostly using Gateway 1.3, and those process variables did not exist for

1147

Gateway 1.3. This Gateway is running on the machine Hydra. The values for

1148

Hydra84 and Rhea are white because these Gateways are not visible from Hydra.

1149

Similarly, the Gateways running on Rhea and Hydra84 do not see the other two.

1150

The Gateways labeled r431 through r438 are reverse Gateways that allow the

1151

internal process variables for all the Gateways 1-34 to be seen on one MEDM

1152

screen. See below for a discussion of <a href="#ReverseGateway">Reverse

1153

Gateways</a>.

1154

1155

The existTestRate for the reverse Gateways, whose server side is on the

1156

machine network, is similar to that seen by all IOCs and servers on the

1157

machine network and is used for monitoring channel access activity on that

1158

network.

1159

1160

<h2><a name="Gateway">Gateway Configurations</a></h2>

1161

1162

<h3><a name="SymmetricGateways">Symmetric Gateways</a></h3>

1163

1164

The following shows a configuration in which each of three networks has a

1165

Gateway that finds process variables in IOCs on the other two networks. This

1166

is a configuration used at BESSY.

1167

1168

However, note that if you are on say, Net A, and using the Gateway whose

1169

server is on Net A, then the client side of this Gateway sees the server side

1170

of the other two Gateways. However, these Gateways each see servers on Net A

1171

and consequently see the Net A Gateway. Therefore, the Net A Gateway can see

1172

process variables on IOCs on Net B and Net C directly and also through the

1173

other two servers. To prevent this loop, each Gateway must be configured to

1174

not allow process variables from the other two Gateways. This can be done

1175

through the -signore <a href="#Starting">command-line option</a>.

1176

1177

<img alt="Symmetric Gateways"

1178

src="SymmetricGateways.gif">

1179

1180

1181

1182

<h3><a name="ReverseGateway">Reverse Gateway</a></h3>

1183

1184

The following configuration shows a reverse Gateway. In this configuration

1185

the four networks, Net A, Net B, Net C, and Net D, each has a Gateway that

1186

gets process variables from Net Z. This is a configuration used at Argonne.

1187

Net Z is the machine network, and the other networks belong to individual

1188

experimental teams. These teams have read access to the machine network and

1189

whatever access they want to the IOCs on their own network. Argonne at

1190

present has eight of these configurations, most with four Gateways plus a

1191

reverse Gateway. Owing to the reverse Gateways, the internal process

1192

variables for all these Gateways can be seen on one MEDM screen, as in the <a

1193

href="#APSGatewaysScreen">example above</a>, through a Gateway that sees

1194

process variables on the machine network. One does not need (and typically

1195

does not have) access to each of these private networks.

1196

1197

To prevent looping, the reverse Gateway only allows the internal process

1198

variables from the other four Gateways and itself, and each of the other

1199

Gateways denies the internal process variables from the other three. As a

1200

result these four Gateways do not see internal process variables from the

1201

other three. They do see the ones from other configurations of four. This

1202

limitation could be overcome by using one reverse Gateway for every regular

1203

Gateway. Note that another Gateway that is not on a network with the client

1204

side of any of the reverse Gateways does not need to deny anything and can

1205

see all the internal process variables from any of the Gateways in any of

1206

these configurations (as in the <a href="#APSGatewaysScreen">example

1207

above</a>).

1208

1209

1210

1211

<h2><a name="AliasGateway">Alias Gateway</a></h2>

1212

1213

It is possible to use the Gateway just to provide aliases for process

1214

variables, and the following configuration shows an alias Gateway. Only one

1215

subnet is needed. If an MEDM asks for the alias name, it is found through the

1216

Gateway. If it uses the real name, it is found through the IOC. The two names

1217

must be different to avoid finding the same process variable in two different

1218

servers.

1219

1220

1221

1222

<h2><a name="ChannelAccess">Channel Access</a></h2>

1223

1224

Channel Access [CA] is the part of EPICS that governs

1225

communication between servers and clients. The two major parts are the

1226

Channel Access Server [CAS] and Channel Access

1227

Client [CAC, sometimes also just CA since there was originally no

1228

CAS]. A CAC, such as MEDM, uses functions in the CAC library for

1229

communication with EPICS and provides its own specific functionality on top

1230

of that. A server uses the CAS library for communication with EPICS and also

1231

provides its own specific functionality. A program that uses CAS is called a

1232

Server Tool to distinguish it from the CAS library itself.

1233

Servers that use CAS are called Portable Servers. The

1234

Gateway is a ServerTool, a Portable Server, a Channel Access Server, and also

1235

a Channel Access Client. There are also Soft IOCs, which,

1236

like Portable Servers, run on platforms such as Solaris, WIN32, and Linux.

1237

These do not currently use CAS and are not Portable Servers.

1238

1239

You can find out more information by looking at the EPICS Channel Access

1240

Reference Manual and the Application Developers Guide. There is a version

1241

included with each EPICS release. They can be found by starting at <a

1242

href="http://www.aps.anl.gov/epics/modules/index.php">IOC Software</a> in the

1243

<a href="http://www.aps.anl.gov/epics/docs">EPICS Documentation</a> and

1244

following links to the release and point release of the desired EPICS

1245

base.

1246

1247

<h2><a name="Acknowledgements">Acknowledgements</a></h2>

1248

1249

Jeff Hill of Los Alamos National Laboratory, the person responsible for <a

1250

href="#ChannelAccess">Channel Access</a>, was of great help in developing the

1251

Gateway throughout its entire development.

1252

1253

<h2><a name="Copyright">Copyright</a></h2>

1254

1255

The Gateway is governed by the <a

1256

href="http://www.aps.anl.gov/epics/license/index.php">EPICS Open

1257

License.</a>

1258

<hr>

1259

1260

<a href="http://validator.w3.org/check/referer"><img

1261

src="valid-html401.png" alt="Valid HTML 4.01!" border="0" align="right"

1262

height="31" width="88"></a>

1263

</body>

1264

</html>