EPICURE Design Note 133.3<P> <b> EPICURE Query Language (EQL)</b>

EPICURE Design Note 133.3

EPICURE Query Language (EQL)

David M. Kline

The EPICURE Query Language was developed in response to the EPICURE review committee's request for a simple and consistent method to access device information from the central database, and the data acquisition system. This design specification intends to describe the commands and philosophy behind the EPICURE Query Language.

Introduction

The EPICURE Query Language is meant for operators, experimenters, and other users of the EPICURE control system who need to review devices from the central database, and perform simple device sets and reads from the data acquisition system without writing an application program. EQL implements a set of easy-to-use commands that can be executed interactively from the prompt (see below) or as a command procedure similar to OpenVMS DCL. It has been designed so that additional commands can be incorporated easily into the command language.

Commands can be executed interactively by passing parameters to the DCL keyword EQL. To illustrate, in order to read a device's current reading the following command can be used: (see next section).

	$ EQL READ M00V

By depressing the return key, EQL sets up the necessary data acquisition calls to return and display the device's current reading to the terminal. If the user wants to execute more than one command, EQL can be invoked by typing the ``EQL'' command at the DCL prompt:

$ eql
EPICURE Query Language V1.0
Device query and command system
Type HELP for assistance
EQL>

For more than one read from the database or data acquisition system, invoking EQL in the above manner is more efficient. This is because all the necessary network connections are made only once.

An additional feature of EQL is that a command procedure can be invoked either interactively or as a batch job. The user creates a command procedure similar to an OpenVMS DCL command procedure. The EQL command procedure has a file extension of ``.EQL'', whereas an OpenVMS DCL commands procedure has an extension of ``.COM''. EQL command procedures can be invoked similarly to executing EQL commands by passing the file name with the character ``@'' in front of it.

	$ EQL @MYFILE

The extension does not have to be provided. EQL will append the default extension and attempt to execute the command procedure. In addition, EQL command procedures can be invoked from the EQL prompt.

$ eql
EPICURE Query Language V1.0
Device query and command system
Type HELP for assistance
EQL> @MYFILE

Furthermore, EQL command procedures can be executed either as a batch job or as a subprocess using the OpenVMS DCL spawn command .

Getting Started

EQL can be accessed from the MENU or the DCL prompt. The user selects EQL from the EPICURE MENU (item #4), or defines a symbol and executes it from the DCL prompt.

            From MENU                           From DCL

$ MENU | $ EQL :== $EPICURE_PROGRAMS:EQL Select item #4 | $ EQL | EPICURE Query Language V1.0 | EPICURE Query Language V1.0 Device query and command language | Device query and command language Type HELP for assistance. | Type HELP for assistance. EQL> | EQL>

EQL commands can be entered interactively at the EQL> prompt or can be executed as part of an EQL command procedure (See ``Command Procedures''). To exit the query language, enter the ``EXIT'' command or depress CTRL/Z.

The remainder of this document will specify the EQL commands that are presently implemented and valid qualifiers which can be used with them.

Command Summary

This section describes the commands which are implemented as part of the EPICURE Query Language. The command language is implemented using Digital's Command Language Interpreter (CLI). The commands can be entered from the EQL prompt or through a command procedure. Comments may be included with or without a command. All characters after an exclamation mark (``!'') to the end of the line are ignored and treated as comments. Multiple spaces and tabs outside of quoted text are treated as a single space. Lowercase characters are converted to uppercase, except within quoted text. Optional parameters and qualifiers are encapsulated by the ``['' and ``]'' characters (i.e. ``[device]''). Braces (``{'' and ``}'') surround a list of options, separated by a vertical bar (``|''), require one to be chosen.

EQL Command Descriptions

EXIT
Terminates processing of EQL commands within a procedure or interactively. If part of a command procedure, the user is returned to either the DCL or EQL prompt. Otherwise, the user is returned to the DCL prompt.

GOSUB label
Transfers control to a label in a command procedure. This command is available only in command procedures.

label
When the GOSUB command is executed, control passes to the command following the specified label. The label can precede or follow the GOSUB statement in the current command procedure. When you use a label in a command procedure, it must be terminated with a colon (See ``Labels'') and cannot be duplicated.

Examples:
This example command procedure shows how to use the GOSUB command to transfer control to labeled subroutines. Each subroutine is terminated by the RETURN command.

   GOSUB TEST1
   WRITE SYS$OUTPUT "success completion"
   EXIT
   !
   TEST1:
   WRITE SYS$OUTPUT "This is a subroutine."
   RETURN

GOTO label
Directs the command procedure to branch to the line after the corresponding label. This command is available only in command procedures.

label
When the GOTO command is executed, control passes to the command following the specified label. The label can precede or follow the GOTO statement in the current command procedure. When you use a label in a command procedure, it must be terminated with a colon (See ``Labels'') and cannot be be duplicated.

Examples:
This example demonstrates the use of the GOTO command.

    IF M00V IS RDY
       GOTO LB1
    ELSE
       GOTO LB2
    ENDIF

LB1: WRITE SYS$OUTPUT "Device is READY!" EXIT

LB2: WRITE SYS$OUTPUT "Device is TRIPPED!" EXIT

HELP topic
The HELP command invokes the VMS HELP Facility to display information primarily about the EPICURE Query Language (EQL). This command can be accessed only interactively.

topic
A topic can be specified about EQL commands, or others pertaining to VMS commands, system services, FERMILIB, or EPICURELIB.

Examples:
These examples demonstrate how to access help about EQL, and other facilities, such as FERMILIB, EPICURELIB, or VMS help. To do so, use the corresponding keywords passing them as parameters to the HELP command.

    1. EQL> HELP
    2. EQL> HELP EQL
    3. EQL> HELP EPICURELIB DA_

IF-ELSE
Compares the readback of a specified device with another device readback or value. Executes one or more commands following the IF command if the condition is true; otherwise executes one or more commands following the ELSE command. The IF-ELSE or IF command MUST be closed by an ENDIF command. This command is available only with command procedures.

    IF device [/qual] operator {device|value|keyword} [/qual]
        command(s)
    [ELSE
        command(s)]
    ENDIF

device
The first parameter after the IF command MUST be a device name. An optional qualifier can be specified indicating the property to read. If no qualifier is present, the READING property is assumed.

Valid qualifiers include /READING, /SETTING, and /STATUS. Values readback from the device are assumed to be in engineering units unless generic or extended status is specified.

operator
The second parameter specifies the logical operator used to compare the first and third parameters. Operators are specified by using the keywords LT, LE, GT, GE, EQ, IS, or NE (See below). No qualifiers are allowed. For generic and extended status, the only operators available are EQ, IS, and NE. The valid operators for comparison include:

    LT - Less than (i.e. "<")
    LE - Less than or equal to (i.e. "<=")
    GT - Greater than (i.e. ">")
    GE - Greater than or equal to (i.e. ">=")
    EQ - Equal to (i.e. "=")
    NE - Not equal to (i.e. "!=")

{device|value|keyword}
The third parameter specifies another device, value, or keyword to compare the device specified in the first parameter with. As with the first parameter, an optional qualifier can be specified indicating the property to read. If no qualifier is present, the READING property is is assumed. Generic and extended status can be tested by providing keywords. See ``Generic_Extended_Status'' for details.

Valid qualifiers include /READING, /SETTING, and /STATUS. Values readback from the device are assumed to be in engineering units unless generic or extended status is specified.

/READING
This qualifier specifies that the data returned from the device's READING property is to be use for comparison.
/SETTING
This qualifier specifies that the data returned from the device's SETTING property is to be used for comparison.
/STATUS
This qualifier specifies that the data returned from the device's STATUS property is to be use for comparison.
Generic_Extended_Status
Generic and extended status can be tested by specifying keywords in the third parameter. Valid generic status keywords include: ON, OFF, RDY, TRP, REM, LCL, NEG, POS, RMP, and DC. Keywords used to test for extended status are dependent on the clear and set text supported by the device. To view the extended status of a device, use the EQL SHOW command with the BITNAMES keyword after the device name (i.e. SHOW M00V BITNAMES) or the DBEdit application.
Examples:
These examples show how to use the IF-ELSE command.
    1. IF DATE EQ 2.1
           WRITE OUTPUT "It's my birthday!"
       ENDIF

The above example shows how the IF-ELSE construct can be used to output a written phrase on a particular date.

2. IF OUTSIDE_TEMP GE 90 WRITE OUTPUT "It's too hot today, no walk!" ELSE IF OUTSIDE_TEMP LE 75 WRITE OUTPUT "What a beautiful day, I'll go walking" ENDIF ENDIF

This example uses the data acquisition system to indicate when the outside temperature reaches particular degrees.

3. IF M00V /READ EQ M00V /SET WRITE OUTPUT "M00V read and set are OK" ELSE WRITE OUTPUT "M00V read and set NOT EQUAL!" ENDIF

This example reads the device "M00V" reading and setting properties and compares the readback values.

4. IF M00V EQ TRP WRITE OUTPUT "Oh no, M00V is tripped!" ENDIF

The above example shows how the IF-ELSE construct can be used to indicate when a device is tripped.

5. IF EC091C0 EQ CLOCK WRITE OUTPUT "EC091C0 has Tev clock" ENDIF

The above example shows how extended status can be tested using the device's clear and set text.

MAIL [directory
filespec username [/SUBJ=``test'']] This command can be used to send a message to other users of the system. A message can be a file, or text using the /SUBJ qualifier. If the user does not want to send a file, the ``NOFILE'' keyword can be substituted in the ``filespec'' parameter. The command can be used in both interactive and command procedure modes.

filespec
Specifies an optional file containing message text to be sent to the specified users. No wild card characters are allowed in the file specification. If the user does not want to send a file the ``NOFILE'' keyword can be specified. If the file name is located some place other than the current directory, the directory path name must precede the file name.
username
Specifies one or more users to receive the message. If any user is on a remote node, you should precede the username with the name of the remote node followed by two colons (i.e. WARNER::BONZO).

As an alternative to listing the user names, you can specify a distribution list file containing user names. Precede the file name with an at sign (@) and enclose it in quotation marks (i.e. ``@OPERATORS''). The file you specify should contain the user names (one per line). The default file type is DIS. No wild card characters are allowed in the distribution list file specification.

/SUBJECT=``text''
Specifies the subject of the message for the heading. The text should be enclosed in quotation marks (i.e. /SUBJECT=``THIS IS A MESSAGE''). If the qualifier is not specified, the text contains a predefined message indicating that the message was from EQL and who sent it.
Examples:
These examples show how to use the MAIL command.
    1. EQL> MAIL SYS$LOGIN:FILE.TXT OPS

This example shows how to send a mail message contained in the file "FILE.TXT" located in the users SYS$LOGIN directory. The predefined message, as described above, is the subject.

2. EQL> MAIL NOFILE MO,LARRY,CURLY /SUBJ="Hello"

This example shows how to send a message in the subject to users MO, LARRY, and CURLY.

3. IF M00V IS TRP MAIL NOFILE OPS,LOGGER /SUBJ="M00V is tripped!" ENDIF

This example demonstrates how the mail command can be used to signal device failures in a command procedure to more than one user.

4. READ M00V /OUTPUT=M00V_READING.DAT IF M00V EQ TRP MAIL M00V_READING.DAT OPS /SUBJ="Bad M00V reading" ENDIF

This example shows how a device reading could be mailed to a user.

5. EQL> MAIL SYS$LOGIN:FILE.TXT "@LIST"

This example shows how to send a mail message contained in the file "FILE.TXT" located in the users SYS$LOGIN directory to a distribution list.

NOVERIFY
Disables echoing commands read from a command procedure or entered interactively.

READ device [/qual ... /qual
] Reads a single device from the data acquisition system. If no qualifiers are specified, the defaults are /READING, /NOSETTING, /NOSTATUS, /WAIT, /OUTPUT=SYS$OUTPUT, /REPEAT=1, and an FTD of immediate. If a device name is not supplied, a ``_Device:'' prompt string is displayed asking the user to enter a name.

device
Specifies the device name to read from the data acquisition system.

/READING[=sym
] This qualifier specifies that the data returned from the device's READING property is to be output (see /OUTPUT qualifier).

The optional ``sym'' is a text string (no quotes) of a symbol that will appear in the process DCL tables after data has returned. The value is converted to engineering units and is assigned to the symbol and can be processed by other DCL commands.

/SETTING[=sym
] This qualifier specifies that the data returned from the device's SETTING property is to be output (see /OUTPUT qualifier).

The optional ``sym'' is a text string (no quotes) of a symbol that will appear in the process DCL tables after data has returned. The value is converted to engineering units and is assigned to the symbol and can be processed by other DCL commands.

/STATUS[=sym
] This qualifier specifies that the device's generic status is to be output (see /OUTPUT qualifier).

The optional ``sym'' is a text string (no quotes) of a symbol that will appear in the process DCL tables after data has returned. The raw value is assigned to the symbol and can be processed by other DCL commands.

/EXTENDED_STATUS[=sym
] This qualifier specifies that the device's extended status is to be output (see /OUTPUT qualifier).

The optional ``sym'' is a text string (no quotes) of a symbol that will appear in the process DCL tables after data has returned. The raw value is assigned to the symbol and can be processed by other DCL commands.

/WAIT
When this qualifier is specified, the EQL prompt will not appear until the data has returned for the specified device. This process can be interrupted by depressing the <RETURN> key. When the /NOWAIT qualifier is specified, the EQL prompt appears immediately.

/OUTPUT[=filespec
] Controls where the output is sent. By default, the display is written to the SYS$OUTPUT device; however, a directory and file name can be specified. No wildcard characters are allowed. If the /NOOUTPUT qualifier is used, output is suppressed.

If only a file name is specified, the file will be placed in the current directory.

/REPEAT[=n
] This qualifier specifies the number of times the device will be read (i.e. /REPEAT=2). In addition, the keyword ``FOREVER'' can be specified indicating that the device is to be read indefinitely. The keyword is supported only when the /WAIT qualifier is present and is not supported in BATCH procedures.

/UNITS[=n
] This qualifier specifies whether to output the device reading in raw, engineering, or intermediate units. Particular characters are used to indicate the units. To specify the units in raw, engineering, or intermediate, use the characters R,E, or I, respectively. If the /UNITS qualifier is not present, the units are output in engineering units, similar to page. This affects the output of the /READING and /SETTING qualifiers. It has no effect on /STATUS.

/FTD[={event[;interval
|Fx}]] This qualifier specifies a rate a which the device will be read. If the /REPEAT qualifier is not specified or is specified with a 1 (i.e. /REPEAT=1), the read will occur only once at that FTD. The keyword ``NOW'' can be specified which represents an immediate FTD. If the qualifier is not present, the FTD is considered immediate. If it is specified without any event, interval, or Fx, the FTD is retrieved from the database.

The fields event, interval, and Fx, indicate the following:

event
Specifies an event in Phase or Tev events. Specifying a format of ``Tn'' indicates the use of a Phase event and a number (i.e. T5); whereas, using the format ``Xn'' indicates the use of a Tev event and a number (i.e. XA0).
interval
Specified the number of milliseconds to delay after the event occurs (i.e. 2000 = 2 seconds).
Fx
Specifies a delay to wait in milliseconds. The ``F'' designates the delay as a frequency FTD (i.e. F1000 = every second) and ``x'' is the number of milliseconds to delay.

Examples:
These examples show how to use the read command.
    1. EQL> READ M00V

The READ command initiates data acquisition for device ``M00V''. The data returns once and immediately for the READING property.

2. EQL> READ M00V /FTD=T1;1000

The READ command with the /FTD qualifier waits for T1 plus 1 second to elapse before returning. This process can be interrupted by depressing the return key.

3. EQL> READ M00H /STATUS=DEVICE_STATUS

The READ command with the qualifier /STATUS=DEVICE_STATUS initiates data acquisition for M00H, outputs the returned information to SYS$OUTPUT and assigns it to the symbol ``DEVICE_STATUS''.

RETURN
Terminates a GOSUB subroutine procedure and returns control to the command following the calling GOSUB command.

RUN [directory
filepsec] Spawns a subprocess and executes the program specified in the parameter. You can specify an image name with an explicit version number (or a semicolon [;]) and a specific directory. The output of the program is directed to SYS$OUTPUT. If the command procedure is executing in BATCH mode, the output is placed into the log file (if specified); otherwise, it is output to the terminal. This command can be executed as part of a command procedure (EQL) only.

filespec
Specifies an executable image to be executed. The file type defaults to EXE. Wildcard characters are not allowed.
Examples:
These examples show how to use the read command.
    1. RUN SYS$LOGIN:MYPROG

The image MYPROG located in the user's home directory is executed.

2. IF EC091C0 EQ OFF RUN SYS$LOGIN:MYPROG ENDIF

This example shows that programs can be executed for a particular criteria on a device.

SET device value [/qual ... /qual
] A device analog or digital setting can be performed by this command. The command interprets the input as either an analog or digital setting. If neither can be deciphered, an error message is output. If no FTD is specified, the setting is immediate. Analog settings are verified whereas digital are not. If the device name is not provided, a ``_Device:'' prompt string is output. Furthermore, if a setting is not provided, the ``_To What:'' prompt string is output. Both parameters MUST be provided before the command can be processed.

device
Specifies the device to set.

value
Specifies the analog or digital setting. Analog values can be entered in engineering (default), intermediate, or raw values. Digital values can be entered in both as generic and extended status. Generic status keywords include: RESET, ON, OFF, POS, NEG, RAMP, and DC. The extended status is determined by the specific device.

/CONFIRM
This qualifier prompts the user before the setting actually takes place, asking if they want to proceed (default is yes). Available only interactively.

/FTD[=event[;interval
]] This qualifier specifies at which event the device will be set. If the qualifier is not present, the FTD is considered immediate. Repetitive (i.e. Fx) FTDs are not allowed by the control system.

The fields event and interval indicate the following:

event
Specifies an event in Phase or Tev events. Specifying a format of ``Tn'' indicates the use of a Phase event and a number (i.e. T5); whereas, using the format ``Xn'' indicates the use of a Tev event and a number (i.e. XA0).

interval
Specifies the number of milliseconds to delay after the event occurs (i.e. 2000 = 2 seconds).

/RAW
This qualifier indicates that the value is specified in raw units.

/ENGINEERING
This qualifier indicates that the value is specified in engineering units (default).

/INTERMEDIATE
This qualifier indicates that the value is specified in intermediate units.
/VERIFY
This qualifier is available to analog settings only. A read of the setting data is performed after the setting. The return value is compared and if it is 15% (+/-) of the setting, a message is output.

Examples:
These examples show how to use the set command.
    1. EQL> SET EC091C0 .6
       EQL> SET EC091C0 C350 /RAW
       EQL> SET EC091C0 .8 /FTD=NOW

The device is set immediately in all cases.

2. EQL> SET EC091C0 10 /FTD=T1

The device is set at T1.

3. EQL> SET EC091C0 10 /FTD=T6;1000

The device is set at T6, plus 1 second (1000 milliseconds).

4. EQL> SET M00V RESET

The device is reset.

SHOW device [/qual ... /qual
[keyword]] The show command retrieves information about a specified device from the database system.

device
Specifies the device name to acquire database information about.

Two wildcard characters, the asterisk (*) and percent (%), can be used in the device name to search the database. The asterisk is used to match the entire, or a portion of, the device name (i.e. MCCADA*); whereas, the percent is used to match the position it occupies (i.e. M%%V). If wildcards are present, all qualifiers, except /OUTPUT, are ignored. The output generated provides a list of all device names which satisfy the criteria.

keyword
There are several keywords that can be specified to collect various pieces of information about a device. They are intended to reduce the size of the command line making it easier to request database information. Below defines the keywords that can be specified:
    ALARMS     - The READING and STATUS ALARM properties attributes
                 are output.
    BEAMLINES  - The BEAMLINES property is output.
    BITNAMES   - The STATUS property bitnames attributes are output.
    CTLNAMES   - The CONTROL property ctlnames attributes are output.
    DATAFORMAT - The READING, SETTING, STATUS, and CONTROL properties
                 data format attribute are output.
    SCALING    - The READING, SETTING, STATUS, and CONTROL properties
                 scaling attributes are output.
    PROTECTION - The READING, SETTING, STATUS, and CONTROL properties
                 read and write protection attributes are output.
    SIZES      - The READING, SETTING, STATUS, and CONTROL properties
                 data size attribute are output.
    RATE       - The READING, SETTING, STATUS, and CONTROL properties
                 rate attribute are output.

/ATTR=keyword
This qualifier is used to specify the attribute to output. A single keyword or multiple keywords can be listed to specify the desired attribute. If every attribute is desired, the keyword ``ALL'' can be specified. Valid keywords are listed below:
    ALL        - Collect all attributes.
    ADDR       - Device addressing information
    SIZE       - Return data sizes
    SOURCE     - Data source
    RATE       - Default sample rates
    SCALING    - Units conversion information
    RDPROT     - Data input protections
    WRPROT     - Data output protections
    FUNCTION   - Synthetic device algorithm
    BITNAMES   - Naming status bits
    DISPLAY    - Alarm display information
    MODTYP     - Interface module type text
    CTLNAMES   - Control names and values
    DATAFMT    - Data format (encoded)
    ALMTYP     - Alarm type
    MODLOC     - Module location

/BRIEF
This qualifier specifies that a minimal amount of information is to be displayed about the given device. The qualifier is the default and overrides all other qualifiers. The information displayed includes the device NAME, DI, TEXT, and DAP TYPE properties. In addition, the READING, SETTING, STATUS, and CONTROL properties ADDRESSING attribute crate, slot, and channel information is output.

/FULL
This qualifier specifies that all device properties and attributes are to be output.

/OUTPUT[=filespec
] Controls where the output is sent. By default, the display is written to the SYS$OUTPUT device; however, a directory and file name can be specified. No wildcard characters are allowed. If the /NOOUTPUT qualifier is used, output is suppressed.

/PROP
This qualifier is used to specify the property to output. A single keyword or multiple keywords can be listed to specify the desired properties. If every property is desired, the keyword ``ALL'' can be specified. Valid keywords are listed below:
    ALL       - Collect all properties.
    DI        - Device index (default)
    NAME      - Device name (default)
    CLASS     - Device class
    TEXT      - Descriptive text (default)
    READING   - Analog reading
    SETTING   - Analog setting
    STATUS    - Digital reading
    CONTROL   - Digital setting
    RALARM    - Alarm for analog reading
    SALARM    - Alarm for digital reading
    SAVE      - Saveable device
    BEAMLINE  - Beamline associations
    LOCATION  - Location information
    DEVTYP    - Encoded device type
    LIST      - Compound device list
    XTEXT     - Extended descriptive text
    TPLTYP    - Database template type text
    MODLOC    - Module location text
    HISTORY   - Maintenance history text

Examples:
These examples show how to use various commands to access device database information.

    1. EQL> SHO M00V
       M00V         0X00400B1C (4197148) |151 P2 2962                    |
             READING PROPERTY
                     ADDRESSING      - M, CRATE=10, SLOT=19, CHAN=001
             SETTING PROPERTY
                     ADDRESSING      - M, CRATE=10, SLOT=07, CHAN=000
             STATUS PROPERTY
                     ADDRESSING      - M, CRATE=10, SLOT=07, CHAN=000
             CONTROL PROPERTY
                     ADDRESSING      - M, CRATE=10, SLOT=07, CHAN=000

The device information is acquired from the database system.

2. EQL> SHO M00V BITNAMES

..or..

EQL> SHO M00V /PROP=STATUS /ATTR=BITNAMES M00V 0X00400B1C (4197148) |151 P2 2962 | STATUS PROPERTY BITNAMES - BITNO=00, NAME=REM_LOC , OFFTXT=REMOTE , ONTXT=LOCAL BITNO=01, NAME=TRIP , OFFTXT=OKAY , ONTXT=TRIP BITNO=02, NAME=ON_OFF , OFFTXT=ON , ONTXT=OFF BITNO=04, NAME=REV , OFFTXT=REVERSE, ONTXT=NORMAL BITNO=05, NAME=REVREM , OFFTXT=REVREM , ONTXT=REVLOC BITNO=09, NAME=EXT_INT , OFFTXT=INTERNA, ONTXT=EXTERNA

The device status property bitnames information is acquired from the database system.

3. EQL> SHO M%%V M00V MB4V MC2V ME2V ME3V ME4V MW2V MC6V MT3V MW7V ME6V [Total of 11 devices found]

This example illustrates how to search for device names using the percent (%) wildcard character.

VERIFY
Echos commands that are read from a command procedure or entered interactively. The information displayed can be useful for debugging EQL command procedures.

WAIT FTD
Puts your process in a wait state for a specified Frequency Time Descriptor (FTD). The WAIT command is used to delay processing of either the process itself or a set of commands in the procedure. See the READ command for a description of the FTD format.

WRITE file ``quoted string''
Prints the specified text to an output file. The output can be directed to the standard output files by supplying the predefined symbols:

OUTPUT - Prints to where SYS$OUTPUT is pointing. SYS$OUTPUT

ERROR - Prints to where SYS$ERROR is pointing. SYS$ERROR

Command_Line_Editing
The query language supports command line editing which is similar to DCL. The last twenty commands entered can be recalled and modified. Cursor movement is provided in single-character increments (left arrow or CTRL/D, right arrow or CTRL/F), or multi-character increments, to the beginning of the line (CTRL/H), or end of line (CTRL/E). Using CTRL/A toggles between insert and overstrike mode. Deleting characters can be performed by word (line feed or CTRL/J), or to the beginning of the line (CTRL/U or CTRL/X).

Command recall, initiated by the UP-ARROW or CTRL/B, displays the last command entered. The command can be modified using the above mentioned control keys, or reentered by depressing the return key. Previous commands can be recalled by continually depressing the up arrow or CTRL/B, and depressing the down arrow key reverses the process. Below lists the the supported control keys.

    CTRL/A   - Toggle overstrike/insert mode.
    CTRL/B   - Recalls the last command entered.
    CTRL/C   - Returns the user to the DCL prompt.
    CTRL/D   - Moves the cursor one position left.
    CTRL/E   - Moves the cursor to the end of the line.
    CTRL/F   - Moves the cursor one position to the right.
    CTRL/H   - Moves the cursor to the beginning of the line.
    CTRL/I   - Tabs horizontally.
    CTRL/J   - Delete word before cursor.
    CTRL/O   - Discards output.
    CTRL/Q   - Restarts output to terminal.
    CTRL/R   - Redisplay current input.
    CTRL/S   - Stops output to terminal.
    CTRL/T   - Displays current time.
    CTRL/U   - Delete one line.
    CTRL/X   - Delete one line.
    CTRL/Y   - Returns the user to the DCL prompt.
    CTRL/Z   - Exit EQL or execute a command.
    UP-ARROW    - Recalls the last command entered.
    DWN-ARROW   - Moves towards most recently entered command.
    LEFT-ARROW  - Moves the cursor one position left.
    RIGHT-ARROW - Moves the cursor one position to the right.

Command_Procedures
An additional feature of the command language is that a command procedure can be invoked either interactively or as a part of a OpenVMS batch job. The user creates a command procedure similar to OpenVMS DCL. The EQL command procedure has a ``.EQL'' extension instead of ``.COM''. EQL command procedures can be executed by the file name with a ``@'' character in front of it.

Labels
Label names can be defined for branching within command procedures. Duplicate labels are not allowed and will signal a severe error. The label name requires that a colon be placed at the end of the name. Furthermore, this feature is available only in command procedures.

Appendix A: Programming Examples

This appendix will show various programming examples on the use of the EQL command language.

EXAMPLE 1: This first example shows how EQL and DCL can be used together to determine the state of a device.

$ VERIFY = F$VERIFY(0) $!MYCOM.COM $! $! This sample program illustrates how $! EQL symbols can be brought into a $! DCL program. $! $! This program reads device M00V and $! determines it's generic status. $! $! =========================================== $! Local symbols defining generic status. This $! information can be acquired from either the $! database editor or the EQL command: $! $! EQL> SHOW M00V SCALING $! $ READY = %X2 $ RDY_STATE = 0 $ TRP_STATE = %X2 $! $ SAY := WRITE SYS$OUTPUT $ EQL := $EPICURE_PROGRAMS:EQL $! $ EQL READ M00V /STATUS=STATUS_DATA /NOOUTPUT $ SAY "M00V status data: ", STATUS_DATA $! $ IF ((STATUS_DATA .AND. READY) .EQ. RDY_STATE) $ THEN $ SAY "M00V is ready!" $ ELSE $ SAY "M00V is tripped!" $ ENDIF $! $ EXIT

$ @MYCOM M00V status data: %X00DE M00V is tripped!

EXAMPLE 2:
This next example shows how EQL can be called from the
DCL command prompt to read a device's extended status.

$ EQL :== $EPICURE_PROGRAMS:EQL $ EQL READ ESECURITY /EXT ESECURITY |116S: SECURITY SYSTEM| EXTSTS: < 100000000000000010000000000000001000000000000000 > RESET16 DISABL |RESET15 DISABL |RESET14 DISABL |RESET13 DISABL | RESET12 DISABL |RESET11 DISABL |RESET10 DISABL |RESET9 DISABL | RESET8 DISABL |RESET7 DISABL |RESET6 DISABL |RESET5 DISABL | RESET4 DISABL |RESET3 DISABL |RESET2 DISABL |RESET1 ENABLE | PRMT_A DISABL |ACCESS NOACCES |RES_SEQ OK |TMTRP_A OK | KYTREEA OUT |GATES_A OK |ACCESS 0 |ACCESS 0 | ACCESS 0 |PRMT_B DISABL |CRSHBTN OK |TMTRP_B OK | KYTREEB OUT |GATES_B OK |BYPASS INBYPAS |PRMT_B OFF | PRMT_A OFF |PRTY_B OFF |PRTY_A OFF |RADSUMB OFF | RADSUMA OFF |CRIT_B OFF |CRIT_A OFF | $

EXAMPLE 3: The device scaling information, located in the database, can be queried.

$ EQL EPICURE Query Language V1.0 Device query and command system Type HELP for assistance EQL> SHO EC091C0 SCALING EC091C0 0X00401BEB (4201451) |091 - 8 Channel Timer | READING - *undefined* SETTING SCALING - PRIMARY - UNITS=10u , Tp(x)=x COMMON - UNITS=secs, Tc(x)=(x-C1)/C2 CONSTANTS: C1=0.0000E+00 C2=1.0000E+05 C3=0.0000E+00 C4=0.0000E+00 C5=0.0000E+00 C6=0.0000E+00 STATUS SCALING - ON, INV=N, MSK=0X00020000, OFF=NRF, ON=REF REMOTE, INV=Y, MSK=0X00010000, OFF=NCL, ON=CLK POLARITY, INV=N, MSK=0X00000001, OFF=EXT, ON= RAMP, INV=N, MSK=0X00008000, OFF=INH, ON=

CONTROL SCALING - NOT-MERGEABLE - RESET, VALUE=0X00000000 POS, VALUE=0X0000000F RAMP, VALUE=0X00000000 EQL>

EXAMPLE 4: This example demonstrates how device reading, setting, and status properties can be read at a given FTD.

$ EQL EPICURE Query Language V1.0 Device query and command system Type HELP for assistance EQL> READ M00V /READ /SET /STAT /FTD=T1;1500 M00V |151 P2 2962| READ: EU -0.006104amps M00V |151 P2 2962| SET: EU 0.000000amps M00V |151 P2 2962| STATUS: TrpOffIntRemPos EQL>

EXAMPLE 5: This example shows how the reading, setting, and status properties' readback can be assigned to symbols in DCL.

$ EQL READ M00V /READ=READ_DATA /SET=SET_DATA /STAT=STATUS_DATA $ SHOW SYM *_DATA READ_DATA = "-0.006104amps" SET_DATA = "0.000000amps" STATUS_DATA = "%X00DE" $ $ EQL READ ESECURITY /STAT=STATUS_DATA /NOOUT $ sho sym *_DATA STATUS_DATA = "%X800080008000" $

EXAMPLE 6: The last example shows how a device can be set from DCL.

$ EQL SET EC091C0 10

Keywords: EPICURE, EQL

Distribution:

Normal

Security, Privacy, Legal

rwest@fsus04.fnal.gov