Zclient Design Notes


The Zclient is an event driven program written in Tcl 7.4/Tk 4.0 and C. The Graphical User Interface (GUI) is written in Tcl/Tk and C. The Z39.50/TCP routines are written entirely in C. There are two primary classes of events to which the zclient responds: GUI events and Z39.50 events.


Table of Contents


GUI Events

User selects a server.
if currently connected to a server: calls Tcl/Zclient command zdisconnect, and then calls Tcl/Zclient commands zset and zconnect
User initiates "Perform Search".
calls Tcl/Zclient commands zset and zsearch
User selects a title in Document List.
calls Tcl/Zclient command zgetrecord
User selects "Exit Zclient" from "File" menu.
calls Tcl/Zclient command zdisconnect and Tcl command exit

Z39.50 Events

Client receives Initialize Response
calls C routine ap_init() which calls Tcl procedures zp_display_msg and zp_display_dblist and initResponseProc.
Client receives Search Response
calls C routine ap_search() which calls Tcl procedures zp_display_msg, zp_document_display_insert, and zp_document_display_insert_end when displaying with full records or zp_display_title when displaying brief records and zp_display_title when displaying brief records and searchResponseProc in all cases.
Client receives Present Response
calls C routine ap_present() which calls Tcl procedures zp_display_msg, zp_document_display_insert, and zp_document_display_insert_end when displaying with full records or zp_display_title when displaying brief records and presentResponseProc in all cases.


Zclient Tcl Registered Commands (extensions to Tcl)

Command list

zconnect host port
Connect to Z39.50 server using hostname and port number supplied.
zdisconnect
Disconnect from Z39.50 server.
zset category value
Set variables. (exceptionalrecordsize, maximumrecordsize, maximumrecordsreturned, smallsetupperbound, largesetlowerbound, mediumsetpresentnum )
zgetfullrec record_number
Request a full record from server.
zgetrecord record_number record_type
Request a full or brief record from server.
Record types are: F: Full Record, B: Brief record.
zhelp
Display verbose or brief help. Brief is the default.
zsearch [options] terms
Request a search from server using terms supplied.
zstatus
Display status of client.
findranges
find extents of terms in string.

Command File Map

command name       C function name       file where function resides

"zconnect",        Zc_ConnectCmd,        zconnectcmd.c
"zdisconnect",     Zc_DisconnectCmd,     zdisconnect.c
"zset",            Zc_SetCmd,            zsetcmd.c
"zgetfullrec",     Zc_GetFullRecordCmd,  zgetfullrec.c
"zgetrecord",      Zc_GetRecordCmd,      zgetrecord.c
"zhelp",           Zc_HelpCmd,           zhelpcmd.c
"zsearch",         Zc_SearchCmd,         zsearchcmd.c
"zstatus",         Zc_StatusCmd,         zstatuscmd.c
"findranges"	   Zc_FIndRangesCmd,	 zfindranges.c

Related C Functions

Zc_Init()
Registers zclient commands; resides in zcInit.c


Tcp Event Handler

Zc_TcpIOProc()
Tk i/o handler for service socket, handles read input events; resides in zctcpproc.c.

Procedures written in Tcl used by C functions

The procedures below reside in funcs.tcl.
zp_disconnect_notify
this procedure is called when Z39.50 server disconnects from client unexpectedly.
zp_display_reset
this procedure clears the title list box display widget. (used by ap_search.c, showclientinfo.c, and zsearchcmd.c)
zp_display_title brief_title
this procedure inserts a title into the title list box display widget. (used by prise_specific/display_record:display_brief())
zp_document_display_reset
this procedure clears the document display widget. (used by prise_specific/display_record:display_full())
zp_document_display_insert textline
this procedure inserts text into the document display widget. (used by prise_specific/display_record:display_full())
zp_document_display_insert_end
this procedure is called when document insertion is finished (used to turn off the busy cursor); (used by prise_specific/display_record:display_full())
zp_display_msg message
this procedure displays error and information messages on message widget and log text widget. (used by numerous C functions)
zp_reset_termlist
this procedure resets term tag list. (used by prise_specific/display_record:display_full())
zp_display_terms
This procedure hightlights term in document when using prise Z39.50 server. (used by prise_specific/display_record:display_full())
zp_display_dblist
This procedure displays contents of zv_server_dblist (used by ap_init.c)
zp_display_fieldlist
This procedure displays contents of zv_database_fieldlist (used by prise_specific/display_record:display_nlphelp())
initResponseProc
invoked when an initialize response is received, after the initResponse associative array is filled. (filled by ap_tk/ap_init.c)
searchResponseProc
invoked when an search response is received, after the searchResponse associative array is filled. (filled by ap_tk/ap_search.c)
presentResponseProc
invoked when an present response is received, after the presentResponse associative array is filled. (filled by ap_tk/ap_present.c)

Tcl variables set by C functions

zv_document
Tcl array containing contents of last full document requested.
zv_prise_session
set to one if currently attached to a prise server.
titles_array (array)
this array variable holds a copy of received titles.
zv_server_dblist (tcl list)
database list for current server.
zv_database_fieldlist (tcl list)
field list for current database selected by user.
zv_num_records_ret
number of records returned by last search.
zv_max_records_ret
number of records displayed by client.
zv_status
status of client's connection with server.
zv_document (array)
contents of last full document requested.
initResponse (array)
contents of last initialize response, partially implemented
searchResponse (array)
contents of last search response, partially implemented
presentResponse (array)
contents of last present response, partially implemented


Z39.50 Server configuration Tcl variables

These variables are used in the supplied Tcl/Tk implementation. Each array is indexed by server name.

Z39.50 Management variables

prefmsgsz (array)
preferred message size supplied to server during init request.
exceptrecsz (array)
exceptional record size supplied to server during init request.
smallSetUpperBound (array)
small set upper bound supplied to server during search request.
largeSetLowerBound (array)
large set lower bound supplied to server during search request.
mediumSetPresentNumber (array)
medium set present number supplied to server during search request.
description (array)
description of server.
hosts (array)
hostname of server.
ports (array)
portname of server.
contact (array)
contact person for this server.
maxret (array)
maximum records to be returned to user from this server.

Titles Management variables

current_serialno
Zclient serial number of currently displayed document
current_titleframe
Tk window name of title in document list of currently displayed document.
document_rsi (array)
result set position of documents in current result set indexed by serial number (volatile)
document_docid (array)
docids of documents indexed by serial number (persistent)
document_brief (array)
titles of documents indexed by serial number (persistent)
document_terms (array)
term of documents indexed by serial number (persistent)
seen_docid_list
list of document perused by the user during the current relevance feedbak session
document_status
current status of document during relevance feedback session (U-undecided, I-not relevant, R-relevant)
resultset (array)
array of docids of documents in current result set indexed by result set position (volatile)
relevant_docid_list
speaks for itself
viewed_docid_list
speaks for itself


Tcl source files

zclient.tcl
main zclient initialization file.
funcs.tcl
a library of Tcl procedures used by zclient.
servers.tcl
server tables editable by zclient through user interface.
dblist.tcl
list of commonly used databases. Used when connecting to Z39.50 servers using engines other than PRISE.
logging.tcl
Tcl procedures for logging user actions. (optional)


User Event Logging

What is logged?

Log format

The user event log contains four fields separated by colons:
   date-time: event_type: event_description: related information

Specification File

The logging routines look for the pathname of the log directory in the file zclient_eventlog.spec; the routines attempt to open this file first in user's home directory, then in <distribution_root>/defaultdir, and then in /usr/local/etc.

A sample /usr/local/etc/zclient_eventlog.spec follows:

/ir-accounting/experiment1/relevance

If the specification file is in user's home directory the path becomes: <log-directory> otherwise if specification file resides in <distribution_root>/defaultdir or /usr/local/etc, path will be: <log-directory>/<username>. If no specification file is available then the logging is printed on standard output.

The full-qualified name is

/<log-directory>/<username>/zclient_event_<date>.log
E.G.
/ir-accounting/experiment1/relevance/user0004/zclient_event_21May1996.log
or
/<log-directory>/zclient_event_<date>.log
E.G.
/ir-accounting/experiment1/relevance/zclient_event_21May1996.log

Log directory tree organization

Path:
     /<log-directory>/<username>/
Log Files:
     zclient_event_<date>.log

A sample zclient_event_21May1996.log follows:

Tue May 21 13:07:22 EDT 1996; new_session; {-- new user session --}
Tue May 21 13:07:55 EDT 1996; perform_search; {database: Federal_Register_1988-1989, search args: {bees }}
Tue May 21 13:08:03 EDT 1996; full_document; { FR891019-0058, Federal_Register_1988-1989_42842 }
Tue May 21 13:08:16 EDT 1996; full_document; { FR89316-0015, Federal_Register_1988-1989_25994 }
Tue May 21 13:08:34 EDT 1996; full_document; { FR89616-0091, Federal_Register_1988-1989_34345 }
Tue May 21 13:09:02 EDT 1996; full_document; { FR89316-0015, Federal_Register_1988-1989_25994 }
Tue May 21 13:09:41 EDT 1996; full_document; { FR88916-0017, Federal_Register_1988-1989_13990 }
Tue May 21 13:09:53 EDT 1996; full_document; { FR891019-0058, Federal_Register_1988-1989_42842 }
Tue May 21 13:30:00 EDT 1996; perform_search; {database: Federal_Register_1988-1989, search args: {bicycles  }}
Tue May 21 13:30:08 EDT 1996; perform_search; {database: Federal_Register_1988-1989, search args: {bicycles  }}
Tue May 21 13:30:24 EDT 1996; full_document; { FR88817-0104, Federal_Register_1988-1989_11286 }
Tue May 21 13:32:39 EDT 1996; full_document; { FR89713-0097, Federal_Register_1988-1989_36322 }
Tue May 21 13:34:19 EDT 1996; normal_exit; 

Source code

The source code for the logging routines resides in <distribution_root>/tcl/logging.tcl.

Memory Management

The Zclient manages memory directly via calls to the C library routines malloc, calloc, and free as well as indirectly for the encoding and decoding of the Z39.50 protocol data (PDUs) via routines generated by the SNACC ASN.1 compiler. A SNACC routine allocates an initial memory buffer (so-called "nibble memory") when the Zclient begins execution. Later, the PDU decoding and encoding code calls other SNACC routines to parcel out pieces of the nibble memory buffer. If the request for a piece can't be filled in the current buffer, a new one is allocated and added to the buffer chain.

The Zclient contains calls to SNACC-generated Free... routines to free the pieces of nibble memory it uses, but these routines do not currently do anything. They are there to support the option of changing from the use of nibble memory management to direct calls to C library routines. The Zclient frees nibble memory by reseting the memory buffer chain each time it sends a PDU back to the the server. When the chain is reset, all the nibble memory buffers except the first are freed. The first buffer contains default PDU information which we preserve for the life of the Zclient. See ..../zclient/src/lib/zclient/client_pai.c and ..../zclient/src/lib/client_util/send_pdu.c for the calls to the nibble memory intialization and reset routines.


Last modified: 7. August 1996