Previous Chapter Chapter 2: IOC Test Facilities

Chapter 2: IOC Test Facilities

1. Overview

This chapter describes a number of IOC test routines that are of interest to both application developers and system developers. All routines can be executed from the vxWorks shell. The parentheses are optional, but the arguments must be separated by commas. All character string arguments must be enclosed in "".

The user should also be aware of the field TPRO, which is present in every database record. If it is set TRUE then a message is printed each time its record is processed and a message is printed for each record processed as a result of it being processed.

2. Database List, Get, Put

dbl

Database List, format:

  dbl ("<record type>")

Examples

  dbl
  dbl "ai"

This command prints the names of the records in the run time database. If <record type> is not specified, all records are listed. If <record type> is specified, then only the names of the records of that type are listed.

dbgrep

List Record Names That Match a Pattern, format:

  dbgrep ("<pattern>")

Examples

  dbgrep "S0*"
  dbgrep "*gpibAi*"

Lists all record names that match a pattern. The pattern can contain any characters that are legal in record names as well as "*", which matches one or more of any character.

dba

Database Address, format:

  dba  ("<record_name.field_name>")

Example

  dba "aitest"
  dba  "aitest.VAL"

This command calls dbNameToAddr and then prints the value of each field in the dbAddr structure describing the field. If the field name is not specified then VAL is assumed (the two examples above are equivalent).

dbgf

Get Field, format:

  dbgf ("<record_name.field_name>")

Example:

  dbgf "aitest"
  dbgf  "aitest.VAL"

This performs a dbNameToAddr and then a dbGetField. It prints the value of each element of the dbAddr structure as well as the field value. If the field name is not specified then VAL is assumed (the two examples above are equivalent).

dbpf

Put Field, format:

  dbpf ("<record_name.field_name>","<value>")

Example:

  dbpf "aitest","5.0"

This command performs a dbNameToAddr followed by a dbPutField and dbgf. If <field_name> is not specified VAL is assumed.

dbpr

Print Record, format:

  dbpr ("<record_name>",<interest level>)

Example

  dbpr "aitest",2

This command prints all fields of the specified record up to and including those with the indicated interest level. Interest level has one of the following values:

0: Fields of interest to an Application developer and that can be changed as a result of record processing.
1: Fields of interest to an Application developer and that do not change during record processing.
2: Fields of major interest to a System developer.
3: Fields of minor interest to a System developer.
4: Fields of no interest. This is used only for pad fields.

dbtr

Test Record, format:

  dbtr ("<record_name>")

This calls dbNameToAddr, then dbProcess and finally dbpr (interest level 3). Its purpose is to test record processing.

3. Breakpoints

A breakpoint facility that allows the user to step through database processing on a per lockset basis. This facility has been constructed in such a way that the execution of all locksets other than ones with breakpoints will not be interrupted. This was done by executing the records in the context of a separate task.

The breakpoint facility records all attempts to process records in a lockset containing breakpoints. A record that is processed through external means, e.g.: a scan task, is called an entrypoint into that lockset. The dbstat command described below will list all detected entrypoints to a lockset, and at what rate they have been detected.

dbb

Set Breakpoint, format:

  dbb ("<record_name>")

Sets a breakpoint in a record. Automatically spawns the bkptCont, or breakpoint continuation task (one per lockset). Further record execution in this lockset is run within this task's context. This task will automatically quit if two conditions are met, all breakpoints have been removed from records within the lockset, and all breakpoints within the lockset have been continued.

dbd

Remove Breakpoint, format:

  dbd ("<record_name>")

Removes a breakpoint from a record.

dbs

Single Step, format:

  dbs ("<record_name>")

Steps through execution of records within a lockset. If this command is called without an argument, it will automatically step starting with the last detected breakpoint.

dbc

Continue, format:

  dbc ("<record_name>")

Continues execution until another breakpoint is found. This command may also be called without an argument.

dbp

Print Fields Of Suspended Record, format:

dbp

Prints out the fields of the last record whose execution was suspended.

dbap

Auto Print, format:

  dbap ("<record_name>")

Toggles the automatic record printing feature. If this feature is enabled for a given record, it will automatically be printed after the record is processed.

dbstat

Status, format:

  dbstat

Prints out the status of all locksets that are suspended or contain breakpoints. This lists all the records with breakpoints set, what records have the autoprint feature set (by dbap), and what entrypoints have been detected. It also displays the vxWorks task ID of the breakpoint continuation task for the lockset. Here is an example output from this call:

  LSet: 00009  Stopped at: so  #B: 00001   T: 0x23cafac
               Entrypoint: so  #C: 00001   C/S:     0.1
               Breakpoint: so  (ap)
  LSet: 00008  #B: 00001   T: 0x22fee4c
               Breakpoint: output

The above indicates that two locksets contain breakpoints. One lockset is stopped at record "so." The other is not currently stopped, but contains a breakpoint at record "output." "LSet:" is the lockset number that is being considered. "#B:" is the number of breakpoints set in records within that lockset. "T:" is the vxWorks task ID of the continuation task. "C:" is the total number of calls to the entrypoint that have been detected. "C/S:" is the number of those calls that have been detected per second. (ap) indicates that the autoprint feature has been turned on for record "so."

4. Hardware Reports

dbior

I/O Report, format:

  dbior ("<driver_name>",<interest level>)

This command calls the report entry of the indicated driver. If <driver_name> is not specified then the report for all drivers is generated. It also calls the report entry of all device support modules. Interest level is one of the following:

0: Print only a list of modules found.
1: Print additional information.
2: Print even more info. The user may be prompted for options.

dbhcr

Hardware Configuration Report, format:

  dbhcr

This command produces a report of all hardware links. To use it on the IOC, issue the command:

  dbhcr > report

The report will probably not be in the sort order desired so on Unix issue the command:

  sort  report > report.sort

report.sort should contain the sort order you desire.

5. Scan Reports

scanppl

Print Periodic Lists, format:

  scanppl

This routine prints a list of all records in the periodic scan lists.

scanpel

Print Event Lists, format:

  scanpel

This routine prints a list of all records in the event scan lists.

scanpiol

Print I/O Event Lists, format:

  scanpiol

This routine prints a list of all records in the I/O event scan lists.

6. Time Server Report

TSreport

Format:

  TSReport

This routine prints out information about the Time server. This includes:

Slave or Master
Soft or Hardware synchronized
Clock and Sync rates
etc.

7. Access Security Commands

asSetFilename

Format:

  asSetFilename ("<filename>")

This command defines a new access security file.

asInit

Format:

  asInit

This command reinitializes the access security system. It rereads the access security file in order to create the new access security database. This command is useful either because the asSetFilename command was used to change the file or because the file itself was modified. Note that it is also possible to reinitialize the access security via a subroutine record. See the access security document for details.

asdbdump

Format:

  asdbdump

This provides a complete dump of the access security database.

aspuag

Format:

  aspuag ("<user access group>")

Print the members of the user access group. If no user access group is specified then the members of all user access groups are displayed.

asphag

Format:

  asphag ("<host access group>")

Print the members of the host access group. If no host access group is specified then the members of all host access groups are displayed.

asprules

Format:

  asprules ("<access security group>")

Print the rules for the specified access security group or if no group is specified for all groups.

aspmem

Format:

  aspmem ("<access security group>", <print clients>)

Print the members (records) that belong to the specified access security group, for all groups if no group is specified. If <print clients> is (0, 1) then Channel Access clients attached to each member (are not, are) shown.

8. Channel Access Reports

ca_chanel_status

Format:

  ca_chanel_status (taskid)

Prints status for each channel in use by specialized vxWorks task.

client_stat

Format:

  client_stat

Channel Access client status

dbel

Format:

  dbel ("<record_name>")

This routine prints the Channel Access event list for the specified record.

9. Interrupt Vector

veclist

Format:

  veclist

Print Interrupt Vector List

10. Environment Variables

epicsPrtEnvParams

Format:

  epicsPrtEnvParams

Print Environment Variables

11. Database System Test Routines

These routines are normally only of interest to EPICS system developers NOT to Application Developers.

dbt

Measure Time To Process A Record, format:

  dbt ("<record_name")

Times the execution of 100 successive processings of record record_name. Note that process passive and forward links within this record may incur the processing of other records in its lockset. This function is a wrapper around the VxWorks timexN() function, and directly displays its output. Therefore one must divide the result by 100 to get the execution time for one processing of record_name.

dbtgf

Test Get Field, format:

  dbtgf ("<record_name.field_name>")

Example:

  dbtgf "aitest"
  dbtgf  "aitest.VAL"

This performs a dbNameToAddr and then calls dbGetField with all possible request types and options. It prints the results of each call. This routine is of most interest to system developers for testing database access.

dbtpf

Test Put Field, format:

  dbtpf ("<record_name.field_name>","<value>")

Example:

  dbtpf "aitest","5.0"

This command performs a dbNameToAddr, then calls dbPutField, followed by dbgf for each possible request type. This routine is of interest to system developers for testing database access.

dbtpn

Test Put Notify, format:

  dbtpn ("<record_name.field_name>","<value>")

Example:

  dbtpn "aitest","5.0"

This command performs a dbNameToAddr, then calls dbPutNotify and has a callback routine that prints a message when it is called. This routine is of interest to system developers for testing database access.

dblls

List Lock Sets, format:

  dblls  (lock_set)

This command generates a report showing the lock set to which each record belongs. If lock_set is 0 all records are shown, otherwise only records in the specified lock set are shown.

dbls

List Structures: This test routine prints a formatted dump of the internal database structures. It is completely menu driven. Only system developers will be normally be interested in this routine because it assumes that the user understands the internal data structures.

12. Old Database Access Testing

These routines are of interest to EPICS system developers. They are used to test the old database access interface, which is still used by Channel Access.

gft

Get Field Test, Format:

  gft ("<record_name.field_name>")

Example:

  gft "aitest"
  gft  "aitest.VAL"

This performs a db_name_to_addr and then calls db_get_field with all possible request types. It prints the results of each call. This routine is of interest to system developers for testing database access.

pft

Put Field Test, format:

  pft ("<record_name.field_name>","<value>")

Example:

  pft "aitest","5.0"

This command performs a db_name_to_addr, db_put_field , db_get_field and prints the result for each possible request type. This routine is of interest to system developers for testing database access.

tpn

Test Put Notify, format:

  tpn ("<record_name.field_name>","<value>")

Example:

  tpn "aitest","5.0"

This routine tests dbPutNotify via the old database access interface.

Table of Contents

Next Chapter