Database Configuration tools Text editor and VDCT w/ hands-on

1. Masanori Satoh/ KEK, Jan. 27-30, 2009 for EPICS seminar at RRCAT, Indore Database Configuration toolsText editor and VDCTw/ hands-on (*) Many parts are quoted from Dr. N. Yamamoto’s lecture material.

2. Management of Database • Database = *.db file (Record instances) • Text file • There are many ways to edit *.db file • Text editor (most simple way): vi, emacs, etc • VDCT: java application w/ GUI (KEKB Linac Control G.) • Old tools: DCT, GDCT, CAPFAST (KEKB Control G.) • Automatic *.db file generation is also available if you need. (RDB, etc)

3. Management of Database(cont’d) • *.db file: • When an IOCstart up, an iocsh read the database file. • dbLoadDatabase => Load *.dbd file • dbLoadRecords => Load *.db file • dbLoadTemplate => Load *.substitutions file Example: …./iocBoot/iocxxx/st.cmd #!../../bin/linux-x86/example < envPaths cd ${TOP} ## Register all support components dbLoadDatabase "dbd/example.dbd" example_registerRecordDeviceDriver pdbbase ## Load record instances dbLoadTemplate "db/userHost.substitutions" dbLoadRecords "db/dbExample.db","user=myHost" cd ${TOP}/iocBoot/${IOC} iocInit()

4. Management of Database(cont’d) • Example: envPaths file epicsEnvSet("ARCH","win32-x86") epicsEnvSet("IOC","iocexample") epicsEnvSet("TOP","/home/tp/epics/epicsApp") epicsEnvSet("EPICS_BASE","/home/tp/epics/epicsApp/../base-3.14.10")

5. Most Simple Record • record(ai,”myAI:record”){} • Record type : ai (Analogue Input) • Record name: “myAI:record” • If you do not define the field values, a record will be generated by the default values.

6. Record Type • ai/ ao: Analogue input/ output • bi/ bo: Binary input/ oputput • mbbi/ mbbo: Multi-bit binary input/ output • calc/ calcout: calculation • waveform: waveform • fanout: fanout • … • … • …

7. Simple Record record(ai, “myAIRecord”) { field(DESC, “sample record”) field(SCAN, “1 second”) field(DTYP, “Soft”) field(VAL, “0.1”) field(INP, “myCalcRecod PP MS”) } • All record types have DESC, SCAN,DTYP, VAL, etc

8. Simple Record (cont’d) field(DESC, “sample record”) # Record Description field(SCAN, “1 second”) # SCAN: Record Process Timing # Periodic/IO Intr/Event/Soft field(DTYP, “Soft”) # DTYPE: Device Type field(VAL, “0.1”) # VAL: Initial Value field(INP, “myCalcRecod PP MS”) # INP: Data source # depends on DTYP

9. What’s VDCT :Visual Database Configuration Tool • It began as a project funded by the Swiss Light Source developed by Cosylab (http://www.cosylab.com). • Recent development has been funded by the APS, Diamond and the SNS. The code development is being done by Cosylab. (open source license) • Visual Tool for database configuration • Java–based application: It’s executable on many environments. (Linux, Windows, etc ) • Useful tools w/ GUI. • Easy to manage the complex database file.

10. VDCT GUI Example

11. CapFast/EPICS

12. <top>/xxxApp/src files EPICS Application name: myExample dbd/myExample.dbd: Record/ Device definition by EPICS base Record types, device support options, choice menus, and other configuration options are defined in Database Definition files (.dbd). During the IOC boot process, one or more .dbd files are loaded.

13. xxxApp/xxx/Db/Makefile Database should be described in Makefile DB += xxx.db After type “make”, xxx.db will be copied to <top>/db. For many same type of devices, it is convenient for you to use template and substitution files. Templatefile： yyy.template record(ai,”$(USER):aiExample$(NO)”){… } Corresponding substitution： yyy.substitutions file yyy.template { {USER=“mrk”,NO=“1”} {USER=“mrk”,NO=“2”} }

14. Template example userHost.substitutions # Example substitutions file file "db/dbExample1.db" { { user = "masanoriHost" } } file db/dbExample2.db { pattern { user, no, scan } { "masanoriHost", 1, "1 second" } { "masanoriHost", 2, "2 second" } { "masanoriHost", 3, "5 second" } } dbExample2.db record(calc, "$(user):calcExample$(no)") { field(DESC, "Counter No. $(no)") field(SCAN,"$(scan)") field(FLNK, "$(user):aiExample$(no)") ….

15. iocBoot/iocxxx You can use the script “st.cmd” to start iocsh. The commands to load database: dbLoadRecords dbLoadTemplete A vxWorks st.cmd file looks like < cdCommands cd appbinld < iocCore ld < xxxLib cd startup dbLoadDatabase(“../../dbd/xxxApp.dbd”) dbLoadRecords(“../../db/xxx.db”,”user=mrk”) dbLoadRecords(“../../db/yyy.db”,”user=bob”) dbLoadRecords(“../../db/zzz.db”,”user=JO”) dbLoadTemplate(“../../db/templte_file_name”) iocInit

16. How to Get VDCT • Go “cosylab Visual DCT Web page” • http://www.cosylab.com/solutions/particle_accelerators/VisualDCT/ • Then download • Latest Version: 2.5.1271 • *.zip file • VisualDCT.jar, VisualDCT-src-2.5.1271.jar, doc folder, runScript java -cp VisualDCT.jar -DEPICS_DB_INCLUDE_PATH=$EPICS_DB_INCLUDE_PATH com.cosylab.vdct.VisualDCT $* • In EPICS training CD, you can find it. • /opt/epics/extensions/src/VDCT/2.5.1271

17. Getting started:*.db file configuration w/ VDCT • To Start up VDCT • You can use runScript /opt/epics/extensions/src/VDCT/2.5.1271 • *.dbd file in xxxApp/dbd directoory (or use vdct xxxApp/dbd/xxxApp.dbd)

18. VDCT Command Option • Options: • --dbd-file • if this command is followed by the name of a .dbd file, the .dbd file is loaded before database is generated • --enable-global-macros • enables global macro evaluation • --disable-global-macros • disable global macro evaluation • --enable-capfast • enable production of hierarhical names like CapFast • --disable-capfast • disable production of hierarhical names like CapFast

19. VDCT Environment Variables • -DVDCT_DIR=<path> • VDCT_DIR: Default working directory • -DVDCT_CONFIG_DIR=<path> • VDCT_CONFIG_DIR: Default working directory for plugin • -DEPICS_DB_INCLUDE_PATH=<path> • EPICS_DB_INCLUDE_PATH: Database directory • e.g.): java -cp VisualDCT.jar com.cosylab.vdct.VisualDCT -DVDCT_CONFIG_DIR=/users/devl/config/vdct test.dbd test.db

20. Example:Main Window of Visual DCT

21. Example:Keyboard shortcuts • Zoom • In Shift + Right • Out Shift + Left • Selection Shift + Space • Move • Up Ctrl + Up • Down Ctrl + Down • Left Ctrl + Left • Right Ctrl + Right

22. Example:Record creation • On workspace, click right button • Select “new records…” • Or, Double click right button

23. Example:Record creation (cont’d) • Select the Record type • Define the Record name • e.g.) 「 $(user):ai」 • If name already exists it will report it

24. Example:Select Multiple Records • Way to select multiple records • Left button：Select first record • Ctrl +Left button： Select Multiple records • Drag left button ： Select Multiple records

25. Example:Move Record • Move record • Select record • Drag left button and move to any location.

26. Example:Move Multiple Record Move Multiple Record Select mutiple records Drag left button and move to …

27. Example: Link(FLNK)

28. Example: Link(FLNK)

29. Example: Link(INLINK)

30. Example: Alarm Level You can define the Field related to alarm level. HIHI, HIGH, LOW, LOLO, e.g.) field(HIHI, "8") field(HIGH, "6") field(LOW, "4") field(LOLO, "2") field(HHSV, "MAJOR") field(HSV, "MINOR") field(LSV, "MINOR") field(LLSV, "MAJOR") e.g.) http://www.aps.anl.gov/epics/extensions/alh/index.php

31. Example: Edit the Field Variables • Inspector Windows • Show/Edit Record Field Setting • Double click Active • Double click speed can be adjusted: ”View -> settings... ->Visual” menu • Object combo box • Show record name • You can change the selected record. • Property table • Show/ Edit: Field name and value • Select display order (Group/アAlphabetical/DBD definition Order） • Label: ”Value” and ”Name” are reversed!!! • Comment text area • Comment for Record • Status bar • Simple description for field functionality

34. Masanori Satoh/ KEK, Jan. 27-30, 2009 for EPICS seminar at RRCAT, Indore Database Configuration toolsText editor and VDCT:Hands-on Instructions

35. Hands-on (0):Preparation for practice • Set environment variable: • USER=Pcname • export USER (*) PCname: your own PC name • Build EPICS application: • cd • mkdir app • cd app • makeBaseApp.pl –t example myExample • makeBaseApp.pl –i –t example myExample

36. Hands-on (1) • Start VDCT • cd /opt/epics/extensions/src/VDCT/2.5.1271 • ./runScript • Select dbd file • xxx/app/dbd/myExample.dbd • Check the basic functionality • Create a new Record • Make the link

37. Hands-on (2) • Create two ai records and a calc record: • $(user):aitest1, $(user):aitest2, $(user):calctest1 • Modify them so that $(user):aitest2 returns the value of “2x+3x”. (x: value of $(user):aitest1). • Save file as xxx/app/myExampleApp/Db/dbExample3.db • At the same place (under Db directory), modify the Makefile so as to add dbExample3.db. • Modify the xxx/app/myExampleApp/Db/userHost.substitutions. • e.g.) add the lines like file "db/dbExample3.db"{ { user = “PCname"} (*) Pcname is your own PC name. } • Type “make” under myExampleApp directory. • Check app/db/*.db files (Can you find dbExample3.db?) • Example of result: • caput PCname:aitest1 10 • caget PCname:aitest2 • 50

38. Hands-on (3) • Create a record which counts up from 0 to 20, repeatedly, in dbExample3.db. • Edit Alarm level • HIHI: 18 • HIGH: 15 • LOW: 5 • LOLO: 2 • Check it by “camonitor” command. • Hints: • See dbExample1.db file.

39. Hands-on (4) • Try to create a Fibonacci progression record in dbExample3.db. • Fibonacci progression can be expressed by: F0=0, F1=1, Fn+2=Fn+Fn+1 e.g.) 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, … • Hints: • Use calc record, ai record