Dirk Zimoch
90a727c901
Most errors found with: codespell -L cach,thst,odly,aslo,parm,parms,inpu,ges,prset,pevent,ptd,pring,valu,noo,noe,ned,inout,ro,siz,froms,nd,fo,singl,sart,multy,tthe,allong,ment,inate,nodel,tring,alse,ture,thi,wille,numer Some more manually found (its -> it's) c++20: Do not use apostrophe (e.g. can't) in unquoted #error message
330 lines
8.7 KiB
Plaintext
330 lines
8.7 KiB
Plaintext
#*************************************************************************
|
|
# Copyright (c) 2012 UChicago Argonne LLC, as Operator of Argonne
|
|
# National Laboratory.
|
|
# EPICS BASE is distributed subject to a Software License Agreement found
|
|
# in file LICENSE that is included with this distribution.
|
|
#*************************************************************************
|
|
|
|
|
|
=title Printf Record (printf)
|
|
|
|
The printf record is used to generate and write a string using a format
|
|
specification and parameters, analogous to the C C<printf()> function.
|
|
|
|
This record type was included in base.dbd beginning with epics-base 3.15.0.2 .
|
|
|
|
=head2 Parameter Fields
|
|
|
|
The record-specific fields are described below, grouped by functionality.
|
|
|
|
=recordtype printf
|
|
|
|
=cut
|
|
|
|
recordtype(printf) {
|
|
|
|
=head3 Scan Parameters
|
|
|
|
The printf record has the standard fields for specifying under what
|
|
circumstances it will be processed.
|
|
These fields are described in L<Scan Fields|dbCommonRecord/Scan Fields>.
|
|
|
|
=fields SCAN, PHAS, EVNT, PRIO, PINI
|
|
|
|
=head3 String Generation Parameters
|
|
|
|
The printf record must specify the desired output string with embedded format
|
|
specifiers in the FMT field. Plain characters are copied directly to the output
|
|
string. A pair of percent characters 'C<%%>' are converted into a single percent
|
|
character in the output string. A single percent character 'C<%>' introduces a
|
|
format specifier and is followed by zero or more of the standard C<printf()>
|
|
format flags and modifiers:
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
Plus ('C<+>')
|
|
|
|
=item *
|
|
|
|
Minus ('C<->')
|
|
|
|
=item *
|
|
|
|
Space ('C< >')
|
|
|
|
=item *
|
|
|
|
Hash ('C<#>')
|
|
|
|
=item *
|
|
|
|
Minimum Field Width (decimal digits or 'C<*>')
|
|
|
|
=item *
|
|
|
|
Precision ('C<.>' followed by decimal digits or 'C<*>')
|
|
|
|
=item *
|
|
|
|
Length Modifier 'C<hh>' E<ndash> Reads link as DBR_CHAR or DBR_UCHAR
|
|
|
|
=item *
|
|
|
|
Length Modifier 'C<h>' E<ndash> Reads link as DBR_SHORT or DBR_USHORT for
|
|
integer conversions, DBR_FLOAT for floating-point conversions.
|
|
|
|
=item *
|
|
|
|
Length Modifier 'C<l>' E<ndash> Reads link as DBR_LONG or DBR_ULONG for integer
|
|
conversions, array of DBR_CHAR for string conversion.
|
|
|
|
=item *
|
|
|
|
Length Modifier 'C<ll>' E<ndash> Reads link as DBR_INT64 or DBR_UINT64 for
|
|
integer conversions.
|
|
|
|
=back
|
|
|
|
|
|
The following character specifies the conversion to perform, see your operating
|
|
system's C<printf()> documentation for more details. These conversions
|
|
ultimately call the C<snprintf()> routine for the actual string conversion
|
|
process, so are subject to the behaviour of that routine.
|
|
|
|
=over 4
|
|
|
|
=item *
|
|
|
|
'C<c>' E<ndash> Convert to a character. Only single byte characters are
|
|
permitted.
|
|
|
|
=item *
|
|
|
|
'C<d>' or 'C<i>' E<ndash> Convert to a decimal integer.
|
|
|
|
=item *
|
|
|
|
'C<o>' E<ndash> Convert to an unsigned octal integer.
|
|
|
|
=item *
|
|
|
|
'C<u>' E<ndash> Convert to an unsigned decimal integer.
|
|
|
|
=item *
|
|
|
|
'C<x>' E<ndash> Convert to an unsigned hexadecimal integer, using C<abcdef>.
|
|
|
|
=item *
|
|
|
|
'C<X>' E<ndash> Convert to an unsigned hexadecimal integer, using C<ABCDEF>.
|
|
|
|
=item *
|
|
|
|
'C<e>' or 'C<E>' E<ndash> Convert to floating-point in exponent style, reading
|
|
the link as DBR_DOUBLE or DBR_FLOAT.
|
|
|
|
=item *
|
|
|
|
'C<f>' or 'C<F>' E<ndash> Convert to floating-point in fixed-point style,
|
|
reading the link as DBR_DOUBLE or DBR_FLOAT.
|
|
|
|
=item *
|
|
|
|
'C<g>' or 'C<G>' E<ndash> Convert to floating-point in general style, reading
|
|
the link as DBR_DOUBLE or DBR_FLOAT.
|
|
|
|
=item *
|
|
|
|
'C<s>' E<ndash> Insert string, reading the link as DBR_STRING or array of
|
|
DBR_CHAR.
|
|
|
|
=back
|
|
|
|
The fields INP0 ... INP9 are input links that provide the parameter values to be
|
|
formatted into the output. The format specifiers in the FMT string determine
|
|
which type of the data is requested through the appropriate input link. As with
|
|
C<printf()> a C<*> character may be used in the format to specify width and/or
|
|
precision instead of numeric literals, in which case additional input links are
|
|
used to provide the necessary integer parameter or parameters. See L<Address
|
|
Specification|https://docs.epics-controls.org/en/latest/process-database/EPICS_Process_Database_Concepts.html#address-specification>
|
|
for information on specifying links.
|
|
|
|
The formatted string is written to the VAL field. The maximum number of
|
|
characters in VAL is given by SIZV, and cannot be larger than 32767. The LEN
|
|
field contains the length of the formatted string in the VAL field.
|
|
|
|
=fields FMT, INP0, INP1, INP2, INP3, INP4, INP5, INP6, INP7, INP8, INP9, VAL, SIZV, LEN
|
|
|
|
|
|
=head3 Output Specification
|
|
|
|
The output link specified in the OUT field specifies where the printf record is
|
|
to write the contents of its VAL field. The link can be a database or channel
|
|
access link. If the OUT field is a constant, no output will be written.
|
|
|
|
In addition, the appropriate device support module must be entered into the DTYP
|
|
field.
|
|
|
|
=fields OUT, DTYP
|
|
|
|
=head3 Operator Display Parameters
|
|
|
|
See L<Fields Common to All Record Types|dbCommonRecord/Operator Display
|
|
Parameters> for more on the record name (NAME) and description (DESC) fields.
|
|
|
|
|
|
=fields NAME, DESC
|
|
|
|
=cut
|
|
|
|
include "dbCommon.dbd"
|
|
%
|
|
%/* Declare Device Support Entry Table */
|
|
%struct printfRecord;
|
|
%typedef struct printfdset {
|
|
% dset common;
|
|
% long (*write_string)(struct printfRecord *prec);
|
|
%} printfdset;
|
|
%#define HAS_printfdset
|
|
%
|
|
field(VAL,DBF_NOACCESS) {
|
|
prompt("Result")
|
|
asl(ASL0)
|
|
pp(TRUE)
|
|
special(SPC_DBADDR)
|
|
extra("char *val")
|
|
#=type STRING[SIZV]
|
|
#=read Yes
|
|
#=write Yes
|
|
}
|
|
field(SIZV,DBF_USHORT) {
|
|
prompt("Size of VAL buffer")
|
|
promptgroup("30 - Action")
|
|
special(SPC_NOMOD)
|
|
interest(1)
|
|
initial("41")
|
|
}
|
|
field(LEN,DBF_ULONG) {
|
|
prompt("Length of VAL")
|
|
special(SPC_NOMOD)
|
|
}
|
|
field(OUT,DBF_OUTLINK) {
|
|
prompt("Output Specification")
|
|
promptgroup("50 - Output")
|
|
interest(1)
|
|
}
|
|
field(FMT,DBF_STRING) {
|
|
prompt("Format String")
|
|
promptgroup("30 - Action")
|
|
pp(TRUE)
|
|
size(81)
|
|
}
|
|
|
|
|
|
=head3 Alarm Parameters
|
|
|
|
The printf record has the alarm parameters common to all record types.
|
|
L<Alarm Fields|dbCommonRecord/Alarm Fields> lists the fields related to
|
|
alarms that are common to all record types.
|
|
|
|
The IVLS field specifies a string which is sent to the OUT link if if input
|
|
link data are invalid.
|
|
|
|
=fields IVLS
|
|
|
|
=cut
|
|
|
|
field(IVLS,DBF_STRING) {
|
|
prompt("Invalid Link String")
|
|
promptgroup("30 - Action")
|
|
size(16)
|
|
initial("LNK")
|
|
}
|
|
field(INP0,DBF_INLINK) {
|
|
prompt("Input 0")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP1,DBF_INLINK) {
|
|
prompt("Input 1")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP2,DBF_INLINK) {
|
|
prompt("Input 2")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP3,DBF_INLINK) {
|
|
prompt("Input 3")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP4,DBF_INLINK) {
|
|
prompt("Input 4")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP5,DBF_INLINK) {
|
|
prompt("Input 5")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP6,DBF_INLINK) {
|
|
prompt("Input 6")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP7,DBF_INLINK) {
|
|
prompt("Input 7")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP8,DBF_INLINK) {
|
|
prompt("Input 8")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
field(INP9,DBF_INLINK) {
|
|
prompt("Input 9")
|
|
promptgroup("40 - Input")
|
|
interest(1)
|
|
}
|
|
%/* Number of INPx fields defined */
|
|
%#define PRINTF_NLINKS 10
|
|
}
|
|
|
|
|
|
=head2 Device Support Interface
|
|
|
|
The record requires device support to provide an entry table (dset) which
|
|
defines the following members:
|
|
|
|
typedef struct {
|
|
long number;
|
|
long (*report)(int level);
|
|
long (*init)(int after);
|
|
long (*init_record)(printfRecord *prec);
|
|
long (*get_ioint_info)(int cmd, printfRecord *prec, IOSCANPVT *piosl);
|
|
long (*write_string)(printfRecord *prec);
|
|
} printfdset;
|
|
|
|
The module must set C<number> to at least 5, and provide a pointer to its
|
|
C<write_string()> routine; the other function pointers may be C<NULL> if their
|
|
associated functionality is not required for this support layer.
|
|
Most device supports also provide an C<init_record()> routine to configure the
|
|
record instance and connect it to the hardware or driver support layer.
|
|
|
|
=head2 Device Support for Soft Records
|
|
|
|
A soft device support module Soft Channel is provided for writing values to
|
|
other records or other software components.
|
|
|
|
Device support for DTYP C<stdio> is provided for writing values to the stdout,
|
|
stderr, or errlog streams. C<INST_IO> addressing C<@stdout>, C<@stderr> or
|
|
C<@errlog> is used on the OUT link field to select the desired stream.
|
|
|
|
=cut
|