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
• Z39.50 events
• Command list
• Command file map
• Tcp event handler
• Procedures written in Tcl used by C functions
• Tcl variables set by C functions
• Z39.50 Server configuration Tcl variables
• Tcl source files
• User event logging
• Memory management

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

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.

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 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

Zc_TcpIOProc()

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

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)

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

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

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)

What is logged?

• when a user performs a search +
• when a user aborts a search in progress +
• when a user requests a full document +
• when a user marks a document {relevant, undecided} +
• when a user requests enhanced query terms +
• when a user ends relevance-feedback session +
• when a user adds enhanced query terms to query
• when a user cancels addition of enhanced query terms
• when a user exits the program

Log format

   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

/ir-accounting/experiment1/relevance/user0004/zclient_event_21May1996.log

/<log-directory>/zclient_event_<date>.log

/ir-accounting/experiment1/relevance/zclient_event_21May1996.log

Log directory tree organization

     /<log-directory>/<username>/

     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

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.