Coercion Rules

The general encoding rules for coercion commands is as follows:

General Syntax: <lvalue>=<expression>

Data Types

Type	Description
gTag	The first part of a DICOM tag representing the attribute group. Expressed as four hex digits.
eTag	The second part of a DICOM tag representing the attribute element. Expressed as four hex digits.
Integer	Numeric value used and returned in some expression functions, including arithmetic functions.
String	Group of ASCII-numeric and control characters. When non-contiguous, strings must be encapsulated within double quotes (""). Control characters must be preceded by a backslash, as in "\n", "\\" and "\"".

Variables

Variable

Description

@PROCESS

Controls whether processing the object continues or not. That is the object would be stored, forwarded, etc according to the context. If the control variable evaluates to NULL(), then processing the object stops. If the control variable evaluates to true (that is not NULL()), then the object will be processed (stored, forwarded, ...) as usual.
Example: $(@PROCESS)=if(equals((0008,0016),"1.2.840.10008.5.1.4.1.1.1.2.1"),NULL(),$(@PROCESS))
Explanation: if the sop class is Digital Mammography X-Ray Image Storage - For Processing, then sets the processing flag to false, otherwise keeps its previous value (which is true by default).

Ivalues

Ivalue	Description
(gTag,eTag)	DICOM attribute tag. The parentheses are required. After the expression is evaluated, the results are assigned to this attribute.
SEQ(gTag1,eTag1, INo1,gTag2,eTag2 [,INo2,gTag3,eTag3...])	A DICOM sequence attribute. Specified by Tag2 within the INo item in the sequence specified by Tag1, where 0 represents the first item in the sequence. If the sequence Tag1 does not exist in the object, the entire expression is ignored.
USER(fieldName)	Custom database fields in the form USER(fieldName) where fieldName is the Field Name defined in the database configuration file dcfields.conf. Custom database fields are valid on the left and right side of assignments.
$(varName)	Temporary variable in the form $(varName) where varName is a unique string used to identify the variable.

Expressions: Value or a Function

Values

Value	Description
(gTag,eTag)	This returns the value of a DICOM tag. If the DICOM tag does not exist, NULL() is returned. The parentheses are required.
Quoted string	This is in the form, “<string>”. Returns the literal string <string>. The string can contain escaped characters, including “\n”, “\\” and ‘\”’.
SEQ(gTag1,eTag1, INo1,gTag2,eTag2 [,INo2,gTag3,eTag3...])	Returns the contents of the DICOM attribute specified by Tag2 within the sequence specified by Tag1. INo indicates the sequence item instance, where 0 represents the first item in the sequence. Returns NULL() if the attribute does not exist in the INo item of the sequence.
Unquoted string	Non-quoted strings can be used when they contain only contiguous, alphanumeric characters.
USER(fieldName)	Custom database field in the form USER(fieldName) where fieldName is the Field Name defined in the database configuration file dcfields.conf.
$(varName)	Temporary variable in the form $(varName) where varName is a unique string used to identify the variable. Uninitialized temporary values return NULL.
(gTag,eTag),”d”,n	(Retired) This returns the nth field in the DICOM tag (gggg,eeee) value as separated by the delimiter d.

Functions

Function	Description
add(n1,n2[,n3…])	Returns the sum of the integers.
and(a,b)	Return “true” if both a and b are non-NULL.
between(n,min,max)	Returns true if integer string n is greater than or equal to min and less than max. Otherwise, it returns NULL.
codenumber(n)	Returns a coded numeric string based on n. Both n and the result are ascii numeric strings >= 0. Result contains the same number of digits as in n.
codestring(s[,x])	Returns a coded string based on the string s. Characters in string x, if present, shall not exist in the result.
concat(a,b[,c…])	Concatenate the values a and b (and c, etc.) NULL values are treated as an empty string, “”.
contains(a,b)	Return b if string b exists in string a. Otherwise it returns NULL.
dicomAge(d1,d2)	Returns the value d1 - d2 in calendar years, months or days in DICOMcompliant format: nnnY, nnnM, or nnnD. If either d1 or d2 is an invalid date value, or d2 predates d1, NULL is returned.
<empty string>	This is the empty string, “”.
equals(a,b)	Return “true” if a and b are equal, NULL if they are not equal.
if(cond,a,b)	Return a if cond is not NULL, b if cond is NULL.
indexof(a, p)	Return the starting position of pattern p in string a. The first position in string a is 0. Returns -1 if p is not found in a. Returns NULL if p or a is NULL.
not(a)	Return “true” if a is NULL, NULL if a is not NULL.
NULL()	Delete the target lvalue.
or(a,b[,c...])	Return the first non-NULL value.
rnd(n[,seed])	Returns a random number string based on seed, if present, between 0 and n-1.
split(a,d,n)	Return the nth field in a using d as the field delimiter.
strlen(a)	Return the number of characters in string a, or NULL if string a is NULL.
sub(n1,n2)	Returns the sum n1 – n2.
substr(a,from[,len])	Return the len characters in a, starting at position from. The first position is ‘0’. If from extends past the end of the string, the NULL string is returned. If len is omitted, the remaining string is returned.
translate(a,d,i1,o1 [,i2,o2...])	Returns the output value, oN, if the input string, iN, matches the source string, a. If the source string matches no input string, the function returns the default value, d. Source string, a, and input strings, iN, must be String types or NULL(). The default value, d, and output values, oN, can be any type but must all be of the same type.
toLower(a)	Returns the string, a, with all letters converted to lower case.
toUpper(a)	Returns the string, a, with all letters converted to upper case.

Note: In the evaluation of expressions, NULL is not the same as the empty string, “”. If a DICOM attribute does not exist, it is NULL. If it exists, but contains a 0-length value, it is the empty string, “”.

An example of a coercion rule:

Insert a prefix, "PFX", before the Accession Number (0008,0050) is below

If the attribute 0008,0050 exists, even if it contains a 0-length value - insert "PFX" into the beginning of the existing value and assign it back to the original attribute
If the original attribute does not exist - return NULL(), which prevents it from being added to the object.
(0008,0050)=if( (0008,0050) , concat(“PFX”,(0008,0050)) , NULL() )

To coerce a comma-separated patient name, (0010,0010)

Defined as "LASTNAME,FIRSTNAME[,MI]" into DICOM-compliant patient name string, "LASTNAME^FIRSTNAME[^MI]"
(0010,0010)=concat(split((0010,0010), ",", 1), "^", split((0010,0010), ",", 2), if(split((0010,0010), ",", 3), "^", ""), split((0010,0010), ",", 3) )

An example of translating a string of defined values to an enumerated set of values for conventional or space-saving purposes, such as in mammography view positions, might look like the following. It converts "cranio-caudal" to "CC" and "medio-lateral oblique" to "MLO", and assigns the abbreviated value to the Series Description attribute. In this example, the view code value is obtained from the first sequence item in the View Code Sequence (0054,0220).

(0008,103e)=translate( SEQ(0054,0220,0,0008,0104), SEQ(0054,0220,0,0008,0104), "cranio-caudal", "CC", "medio-lateral oblique", "MLO" )

Note: Line breaks in each example are inserted for readability only. To work, these commands must be entered on a single line.

To swap two values, define a three-step process:

Assign the value from one attribute to a temporary attribute
Copy the value from the second attribute to the first attribute
Copy the value in the temporary attribute to the second attribute