Name Regular Expressions
The reflector DBM can be asked to search for a common name by means of a
Basic UNIX regular expression applied to
all common names known to the DBM.
A regular expression search is useful when part of the name is known, or the exact spelling of the name isn't known. With
special regular expression characters one can specify a generalized method for matching common name strings.
Symbol
A name regular expression search is a standard lookup command ('l', PUIDNETD_CMD_LOOKUP) with a regular expression key.
Keys
The regular expression key is presented to the reflector DBM in a PUIDNETD_DATA_RE field, 'r'. The field has three parts.
- A limit on the number of possible matches that will be returned, followed by a comma (','),
- A limit on the amount of real time in milliseconds the DBM should spend searching for matches, followed by a comma,
- The regular expression itself.
The count and time limits may be blank, replaced by two leading commas (",,"). In that case the defaults are used. (See Regular Expression Limits.)
Case
The case of letters in the regular expression and the names to which it is matched is always ignored.
Reply
A positive acknowledgement (ACK) reflector reply message may contain these fields. The field identifier symbols come from puidnetd.h
a -- an alias (PUIDNETD_DATA_AKA); it accompanies an ACK reply.
N -- a common name (PUIDNETD_DATA_CNM); it accompanies an ACK reply.
p -- PUID (PUIDNETD_DATA_PUID); a unique PUID; it accompanies an ACK reply.
A negative acknowledgement (NAK) reply will contain these fields.
e -- an error code (PUIDNETD_DATA_ERRC); it accompanies a NAK reply.
M -- a message (PUIDNETD_DATA_MSG); it accompanies a NAK reply.
Examples
Here are some examples using a regular expression to search for names ending in "smithson". (The ending '$' anchors the
search at the end of the name.)
This example asks for no more than 5 replies:
External protocol lookup command message:
l 5,,smithson$
Positive acknowledgement (ACK) reply:
a NJAMES SMITHSON p18 asmithsonj
Negative acknowledgement (NAK) reply:
n\te17\tMPerson not found (75)\t
MThere are 2 possible matches:\t
M 26(smithsonj) JAMES SMITHSON\t
M 34(smithsonr) ROBERT SMITHSON\t\r\n
17 is the external protocol PUIDNETD_EDBME error code. 75 is the internal protocol error number from the DBM, expanded in
the first part of the message (PUIDNETD_DATA_MSG) field. The last three message fields give the possible match count and
the possible matches.
This example asks for no more than one reply, taking no more than 500 milliseconds (one half second) of search time:
l r1,500,smithson$
NAK over-time-limit response:
n\te17\tMPerson not found (75)\t
MTime over 0.500 sec; 0 matches in that time
The "0 matches in that time" message indicates no matches were found in the allotted time.
Finally, here's the lookup command, using the default count and time limits:
l r,,.*bar$
NAK over-count-limit response:
n\te17\tMPerson not found (75)\t
MMatch count over 1\t\n\r
Regular Expression Limits - The first two arguments in the PUIDNETD_DATA_RE field are count and time limits. Their defaults, minima, and maxima are:
- Count -- a default of 25, a minimum of one, and a maximum of 25;
- Time -- a default of 1,000 milliseconds (one second); a minimum of 10 milliseconds; and a maximum of 1,000 milliseconds (one second).