%DocEntities; ] > Aleksandar Bakić MSU Graduate Research Assistant Michigan State University Department of Computer Science

East Lansing Michigan 48824 U.S.A. bakicale@cps.msu.edu

Release 1.0 July 15, 1998 1996–1998 MSU Board of Trustees Module (pgrt main) defines functions that are used by the other modules of the &PGRT;-TIE environment. Some of them are just renamed standard Scheme or GUILE procedures, for convenience, while the others are relatively simple utility functions. See also the &R5RS; or &R4RS; standard and GUILE (http://www.red-bean.com/guile/docs/) User's and Programmer's manuals. (use-modules (pgrt main)) These functions are either very primitive ones or just renamed simple GUILE Scheme procedures. bool->string Converts a Scheme Boolean to a string (Tk-compatible Boolean). (bool->string val) val A Scheme Boolean value (either #t or #f). If val is #t, bool->string returns "1". If val is #f, bool->string returns "0". This function is added for passing Boolean values to Tk. (bool->string #t) returns "1". fork A wrapper for POSIX fork system call. (fork) None. fork renames GUILE's primitive-fork for convenience. It creates a new process with the same core image as the current process. fork returns #f upon failure; otherwise, the child gets a return value of 0, and the parent gets the child's pid. This function depends on future GUILE development. Note that the child process will use the same file descriptors as the parent by default. The following code dispatches program my_prog and proceeds without waiting for it to terminate. (if (= 0 (fork)) (apply execpl '("my_prog" "my_prog"))) basename Trims the directory of a full-path filename. (basename filename) filename The filename. basename uses a regular expression to match the part of filename after the rightmost /. If successful, returns the result of matching. Otherwise returns #f. None. (basename "/usr/bin/GUILE") returns "GUILE". forced-display Calls display and flushes current output port. (forced-display datum) datum The datum to be displayed using display. forced-display is same as display, except that it calls force-output after displaying its parameter. This function is supposed to be used for debugging purposes. (forced-display my-variable) displays the value of my-variable and flushes the output buffer. list-set! Binds a value to an element of a list. (list-set! lst ind val lst The list to be updated "in place." ind The index of the element to be assigned the new value. val The value to be assigned to the element. list-set! combines set-car! and list-tail to bind val to the ind-th element of lst. This function creates a side-effect, i.e., it modifies its argument. If lst is '(1 2 3 4), the following call (list-set! lst 2 'a) will change lst to '(1 2 a 4). l-r, l-s!, v-r, v-s! Synonyms for list-ref, liset-set!, vector-ref, and vector-set!, respectively. See the reference for list-set! and &R4RS; or &R5RS; document. list-index Returns the index of an element of a list. (list-index lst elt) lst A list. elt The element whose index within lst is to be computed. If elt is an element of lst, i.e., it is equal in the sense of equal? to an element of lst, then list-index returns its position within lst. Otherwise, it returns #f. None. The following code returns 1. (list-index '(1 a 2 "b") 'a) nth Returns n-th element of a list. (nth n lst) n The index of the element to be returned. lst A list. If successful, nth returns the n-th element of lst. If lst is empty or n is negative or larger than the length of lst, nth returns #f. None. The following code returns "b". (nth 2 '(a 1 "b" 2)) These functions allow a programmer to maintain association lists (lists of key-value pairs) with keys being numbers (functions with prefix id-) or strings (functions with prefix alias-). They are used at various places in &PGRT;-TIE components for maintaining small associative databases. See also SLIB manual, the section on data structurs. id-put Adds/replaces a key-value pair to an association list. (id-put alst key val) alst The association list to be added/replaced the key-value pair. key A number, the key under which val will be stored in alst. val The value associated with key. id-put takes a possibly empty association list alst and stores a pair consisting of key and val into it. If alst already contains data with the same key, that data is lost. id-put then returns the new association list. For key equality testing, predicate = is used. This function does not have side effects. In order to modify an association list, code like in the example below should be used. The items in an association list are not sorted by key. If my-alist is an association list with numeric keys, the following code will add '(15 . ("a" "list" "of" "words"), by possibly losing existing data associated with key 15, to my-alist (set! my-alist (id-put my-alist 15 ("a" "list" "of" "words"))) id-get Obtains data associated with a key from an association list. (id-get alst key) alst The association list in which to search for data. key The key (a number) under which to search. id-get returns data in alst associated with key if successful. Otherwise, it returns #f. For key equality testing, predicate = is used. None. If my-alist contains key-value pairs representing a few non-negative numbers and their names, namely it is '((0 . "Zero") (1 . "One") ...), the following function takes a non-negative number and returns its name if it is found in my-alist. (define (the-name-of n) (id-get my-alist n)) id-rem Removes a key-value pair from an association list. (id-rem alst key) alst The association list from which the key-value pair is to be removed. key The key (a number) under which to search. id-rem returns a new association list, from which key-value pair with the key equal to key is possibly removed. If there is no data stored under key, alst is returned. For key equality testing, predicate = is used. None. If my-alist is '((1 . a) (2 . b)) and the following code is executed (id-rem my-alist 2) it will return '((1 . a)). id=? An association function corresponding to predicate =. (id=? key alst) key The key (a number) under which to search. alst An association list. id=? returns a key-value pair whose key is equal in the sense of = to its first argument. If there is no data with key equal to key in alst, #f is returned. None. If my-alist is '((1 . a) (2 . b)), then the call (id=? 2 my-alist) returns pair '(2 . b). id-index Returns the index of a key-value pair in an association list. (id-index alst key) alst An association list. key The key (a number) under which to search. id-index returns the position (index) of a key-value pair whose key is equal, in the sense of =, to key. If there is no such pair, #f is returned. Key-value pair in an association list are not sorted by key. If my-alist is '((1 . a) (2 . b)), then the call (id-index my-alist 2) returns 1. id<? Compares numeric keys of two key-value pairs. (id<? pair-1 pair-2) pair-1 A key-value pair whose key is a number. pair-2 A key-value pair whose key is a number. This function compares the keys of pair-1 and pair-2 using <, and returns #t or #f (depending on the result of the comparison). None. The following code processes key-value pairs from my-alist ordered by key (a key is a number). (alist-for-each (lambda (key value) (process key value)) (sort my-alist id<?)) alias-put Adds/replaces a key-value pair to an association list. (alias-put alst key val) alst The association list to be added/replaced the key-value pair. key A string (alias), the key under which val will be stored in alst. val The value associated with key. alias-put takes a possibly empty association list alst and stores a pair consisting of key and val into it. If alst already contained data with the same key, that data is lost. alias-put then returns the new association list. For key equality testing, predicate string-ci=? is used. This function does not have side effects. In order to modify an association list, code like in the example below should be used. The items in an association list are not sorted by key. If my-alist is an association list with string keys, the following code will add '("xyz" . ("a" "list" "of" "words"), by possibly losing existing data associated with key "xyz", to my-alist (set! my-alist (alias-put my-alist "xyz" ("a" "list" "of" "words"))) alias-get Obtains data associated with a key from an association list. (alias-get alst key) alst The association list in which to search for data. key The key (a string) under which to search. alias-get returns data in alst associated with key if successful. Otherwise, it returns #f. For key equality testing, predicate string-ci=? is used. None. If my-alist contains key-value pairs representing a few non-negative numbers' names and values, namely it is '(("Zero" . 0) ("One" . 1) ...), the following function takes a non-negative number's name and returns its value if it is found in my-alist. (define (the-value-of s) (alias-get my-alist s)) alias-rem Removes a key-value pair from an association list. (alias-rem alst key) alst The association list from which the key-value pair is to be removed. key The key (a string) under which to search. alias-rem returns a new association list, from which key-value pair with the key equal to key is possibly removed. If there is no data stored under key, alst is returned. For key equality testing, predicate string-ci=? is used. None. If my-alist is '(("a" . a) ("b" . b)) and the following code is executed (alias-rem my-alist "b") it will return '(("a" . a)). alias=? An association function corresponding to predicate string-ci=?. (alias=? key alst) key The key (a string) under which to search. alst An association list. alias=? returns a key-value pair whose key is equal in the sense of string-ci=? to its first argument. If there is no data with key equal to key in alst, #f is returned. None. If my-alist is '(("a" . a) ("b" . b)), then the call (alias=? "b" my-alist) returns pair '("b" . b). alias-index Returns the index of a key-value pair in an association list. (alias-index alst key) alst An association list. key The key (a string) under which to search. alias-index returns the position (index) of a key-value pair whose key is equal, in the sense of string-ci=?, to key. If there is no such pair, #f is returned. Key-value pair in an association list are not sorted by key. If my-alist is '(("a" . a) ("b" . b)), then the call (alias-index my-alist "b") returns 1. alias<? Compares numeric keys of two key-value pairs. (alias<? pair-1 pair-2) pair-1 A key-value pair whose key is a string. pair-2 A key-value pair whose key is a string. This function compares the keys of pair-1 and pair-2 using string<?, and returns #t or #f (depending on the result of the comparison). None. The following code processes key-value pairs from my-alist ordered by key (a key is a string). (alist-for-each (lambda (key value) (process key value)) (sort my-alist alias<?)) Functions and variables described in this section are for simple registering sources of instrumentation data and visual objects, as well as for reading instrumentation data from trace files. These functions are defined for use in &PGRT; Shell. Once you have mastered their use, you may build you own performance analysis and visualization applications similar to the &PGRT; Shell and extend these functions to suit specific needs. register-vo Registers a visual object with &PGRT;-TIE. (register-vo title vo gui-on gui-off) title The string to be used as the alias of the visual object being registered. vo The visual object. gui-on A function that maps the visual object GUI on screen. gui-off A function that unmaps the visual object GUI off screen. register-vo puts visual object vo, accompanied with the other parameters, into association list vo-alist. The key-value pair corresponding to the parameters has key equal to title, and value equal to a list of vo, gui-on, and gui-off (in that order). If the &PGRT; Shell is running, it also passes its arguments to register-vo-pgrtsh function (see the &PGRT;-TIE Tutorial). Visual objects in vo-alist are not necessarily the ones being passed instrumentation data records for processing and/or called to render the contents of their info-structures; for that purpose, they need be activated by copying them to vo-list. If the &PGRT; Shell is running, the registration will be animated in its window. (register-vo "Gantt" gantt gantt-gui-on gantt-gui-off) registers visual object gantt under name "Gantt", which is a key in the vo-alist association list. register-ds Registers an instrumentation data source with &PGRT;-TIE. (register-ds title ds) title The string to be used as the alias of the instrumentation data source being registered. ds The instrumentation data source, a function or thread without parameters (i.e., a thunk) that receives instrumentation data records and passes them to visual objects in vo-list. register-ds puts pair (title . ds) into ds-alist. If the &PGRT; Shell is running, it also passes its arguments to register-ds-pgrtsh function (see the &PGRT;-TIE Tutorial). To start the instrumentation data source represented by ds, ds needs be called. The following code registers, as an instrumentation data source, recv-a-session-thread that will read PICL records from flops.trf when started. (define flops-reader (lambda () (read-a-session-thread "flops.trf"))) (register-ds (string-append "PICL file: flops.trf") ds) read-a-session Reads instrumentation data records from a trace file. (read-a-session filename) filename The name of the trace file. read-a-session reads line by line from filename in a loop, calling vo-refresh, parsing the lines as PICL records, and passing the results to visual objects in vo-list for processing. The loop stops when either the eof object is read or end-of-session is set to a non-#f value. None. (read-a-session "flops.trf") reads instrumentation data records from tracefile flops.trf and passes them to visual objects in vo-list, until either the end-of-file object is read or end-of-session variable is set to #t. read-a-session-thread A threaded version of read-a-session. (read-a-session-thread filename) filename The name of the trace file. read-a-session-thread creates a thread that reads line by line from filename in a loop, calling vo-refresh, parsing the lines as PICL records, and passing the results to visual objects in vo-list for processing. The thread's loop stops when either the eof object is read or end-of-session is set to a non-#f value. None. (read-a-session-thread "flops.trf") starts a thread that reads instrumentation data records from tracefile flops.trf and passes them to visual objects in vo-list, until either the end-of-file object is read or end-of-session variable is set to #t. voml-read-a-session-thread Similar to read-a-session-thread but with selective calls to vo-process-event. (voml-read-a-session-thread filename) filename The name of the trace file. voml-read-a-session-thread creates a thread that reads line by line from filename in a loop, calling vo-refresh, parsing the lines as PICL records, and passing the results to only those visual objects in vo-list that have requested them for processing. Record and event types of instrumentation data records requested by a visual object generated by the VOML compiler are kept in the visual object's context object (that is read and writted using vo-read-context and vo-write-context functions. For each requested instrumentation data record there is a pair of the form '(record-type . event-type); these pairs are bundled in a list and stored into the associated context object. The thread's loop stops when either the eof object is read or end-of-session is set to a non-#f value. None. (voml-read-a-session-thread "rt-test.trf") starts a thread that reads instrumentation data records from tracefile flops.trf and passes them to visual objects, which were generated by the VOML compiler and do recognize the records, in vo-list, until either the end-of-file object is read or end-of-session variable is set to #t. s-read-a-session Reads instrumentation data records from a trace file and triggers synchronous rendering by visual objects. (s-read-a-session filename maxdelta) filename The name of the trace file maxdelta The maximum logical time interval between two consecutive calls to visual objects' rendering methods. s-read-a-session works similarly to read-a-session, but it assumes that visual objects in vo-list are made for synchronous mode of operation (i.e., the process-event method does not automatically call the draw-info method at its end). Each instrumentation data record read from filename will be passed to visual objects in vo-list for processing, and the visual objects' draw-info methods will be called once maxdelta units of time have passed since the previous call. See also the section on visual objects. s-read-a-session assumes that the time stamp of each instrumentation data record is stored in the third field (i.e., its index in a PICL record is 2). maxdelta should be in the same time units as the time stamps. Assuming that the time stamps are in the third field of each PICL record in flops.trf, and that their values are in seconds, the following code will pass all the records to visual objects in vo-list and draw the contents of info-structures (approximately) every 0.1 seconds. (s-read-a-session "flops.trf" 0.1) parse-picl Converts a PICL string into a list of heterogeneous data. (parse-picl picl-record) picl-record A string containing a PICL-compatible instrumentation data record. parse-picl takes a string, whose content is a number of fields separated by whitespace, containing external (ASCII) representations of heterogeneous data (integers, floating point numbers, and double-quoted strings). It returns a list of Scheme data whose elements correspond to the data in picl-record. If parsing is unsuccessful, an empty list is returned. None. If event is string `-3 4004 2.65 4 5 7 "Sensor" 1 0', the following call (parse-picl event) returns '(-3 4004 2.65 4 5 7 "Sensor" 1 0). pgrtsh-running Initially #f. Indicates whether the &PGRT; Shell is running. vo-list The list of activated visual objects (i.e., the ones being passed instrumentation data records for processing and/or called to render the contents of their info-structures). vo-alist The association list of registered visual objects. See also the reference for register-vo. vo-num The number of registered visual objects. opened-vos The list containing the numbers associated with registered visual objects whose graphical user interfaces are opened. end-of-session Initially #f. Used for stopping receiving of instrumentation data records. ds-list The list of activated instrumentation data sources (i.e., the ones passing instrumentation data records to activated visual objects for processing). ds-alist The association list of registered instrumentation data sources. See also the reference for register-ds. ds-num The number of registered instrumentation data sources. (use-modules (pgrt vo)) High-level Visual Objects can be prototyped in &PGRT;-TIE. The low-level Visual Object class implementation for X Windows was initially written by Peter Wong. depicts the design of the Visual Objects framework. It identifies the two main software layers apparent in a majority of extant performance-visualization tools (in object-priented terms): a high-level visual object (HLVO) class and a low-level visual object (LLVO) class. In general, the responsibility of a HLVO class is to implement an application-specific semantics, while a LLVO class is platform-dependent while providing a platform-independent interface to the HLVO class. When implementing a VO class, a HLVO class implementation is derived from a LLVO class.

A high-level visual object, which is derived from a low-level class implementation, handles these visualization functions, according to : The performance data passed to a HLVO via calls to the processing method are termed events (or data events). Based on the events, this method (1) updates performance information referred to as info structures, and (2) controls the rendering of this information by updating data structures referred to as control structures. The rendering method may be called, to map a portion of the info structures' contents to the LLVO views, either immediately after processing an event (asynchronous rendering mode) or by a process/thread that may synchronize the rendering of multiple HLVOs (synchronous rendering mode). This method communicates with the processing method by both reading and writing the control structures. A HLVO may also respond to changes in its run-time environment, as well as to the user's commands. This method may, for example, preprocess callback events coming from the LLVO, a GUI, etc., and then forward them to the processing method as if they were data events. In on-line performance visualization, it is desirable to be able to reinitialize partially or reconfigure a HLVO without interrupting the target application and/or instrumentation system that supplies performance data. vo-create Creates a visual object. (vo-create n-views adapt-goodness init-fun process-fun draw-fun . callback-fun) n-views An integer that specifies the maximum number of views that the visual object will maintain. The implementation of these views is a part of the low-level visual object class implementation. adapt-goodness An integer that relates to the low-level visual object's ability to adapt to quantitative changes in measurement data. One iterpretation may be the number of most extreme points (in each direction of the Cartesian coordinate system) that the visual object can remember. init-fun Specifies the user-defined Scheme procedure that is called after the high- and low-level visual object initialization has been done. The parameters of init-fun are the visual object and the view ID (a non-negative integer). Returns 1 if successful. process-fun Specifies the user-defined Scheme procedure that processes event traces and updates the visual object's info structures. Parameters of process-fun are a visual object and a Scheme object representing an event (list of numbers and/or strings if representing a PICL event trace record) representing an event trace record. Returns 1 if successful. draw-fun Specefies a user-defined Scheme procedure that reads the contents of visual object's info structures and renders it in the visual object's views. The parameter of draw-fun is a visual object. Returns 1 if sucessful. callback-fun An optional parameter that is a user-defined Scheme procedure called by the low-level visual object when a specific event occurs. The parameters of callback-fun are: the visual object, the view ID, the event type, and a list of view-specific data in the following order: [0] mouse button number, [1] mouse cursor world x coordinate, [2] mouse cursor world y coordinates, [3] the last key pressed, [4] the color of the pixel under the mouse cursor, [5] the width of the view window in pixels, [6] the height in pixels, [7] the world x coordinate of the left edge of the view window, [8] the world y coordinate of the bottom edge of the view window, [9] the world x coordinate of the right edge of the view window, [10] the world y coordinate of the top edge of the view window, and the world dimensions of the [11] top, [12] right, [13] bottom, and [14] left margin, respectively. Returns nothing. vo-create returns a newly created visual object, if successful. Otherwise, it returns #f. Currently, only one LLVO class implementation is available (based on X library) and vo-create doesn't not have a parameter that would specify the LLVO class implementation. This parameter might be added in the future. (define gantt (vo-create 1 8 gantt-init gantt-process gantt-draw)) creats a visual object with one view and stores it in variable gantt. vo-init (Re)initializes a visual object. (vo-init visual-object view-id title width height virt-width virt-height minx maxx miny maxy top-margin right-margin bottom-margin left-margin back-color fore-color adapt-mask) visual-object Specifies the visual object whose view is to be initialized. view-id A non-negative integer that specifies the view of the visual object to be initialized. title A string to be displayed on the upper edge of the view window. width A positive integer, the width of the view window in pixels. height A positive integer, the height of the view window in pixels. virt-width A positive integer, the width of the virtual view window in pixels. If virt-width is greater than width, a horizontal scroll bar is added to the view window (not tested). virt-height A positive integer, the height of the virtual view window in pixels. If virt-height is greater than height, a vertical scroll bar is added to the view window (not tested). minx A real number, the world x coordinate of the left edge of the view window's canvas. It corresponds to the leftmost vertical line of pixels. maxx A real number, the world x coordinate of the right edge of the view window's canvas. It corresponds to the rightmost vertical line of pixels. miny A real number, the world y coordinate of the bottom edge of the view window's canvas. It corresponds to the bottommost horizontal line of pixels. maxy A real number, the world y coordinate of the upper edge of the view window's canvas. It corresponds to the topmost horizontal line of pixels. top-margin A non-negative real number, the width of the margin above the scrollable area, in world dimensions. right-margin A non-negative real number, the width of the margin right of the scrollable area, in world dimensions. bottom-margin A non-negative real number, the width of the margin below the scrollable area, in world dimensions. left-margin A non-negative real number, the width of the margin left of the scrollable area, in world dimensions. back-color A string, the background color of the view window's canvas. fore-color A string, the foreground color of the view window's canvas. adapt-mask A non-negative integer, obtained using bit-wise logical OR of some of the following constants: XPLUS, XMINUS, YPLUS, YMINUS. The constants represents the directions in which the low-level visual object dynamic adaptation to quantitative changes should be performed at run time. vo-init initializes or reinitializes a view of the visual object: it first calls the corresponding function of the low-level visual object, then the user-defined Scheme high-level visual object initialization procedure. It returns what is returned by the user-defined Scheme high-level visual object initialization procedure. None. The view window below will be 400 pixels wide and 200 pixels high, with the scrollable area 100 wide and 100000 high (in world coordinates), and with 10% additional non-scrollable space on each side (the margins). (vo-init vo 0 "Video Application: Received/Lost Throughput" 400 200 400 200 -10.0 110.0 -10000.0 110000.0 10000.0 10.0 10000.0 10.0 "black" "white" YPLUS) vo-read-context Returns a Scheme object associated with a visual object. (vo-read-context visual-object) visual-object Specifies the visual object whose associated Scheme object is to be returned by this procedure. vo-read-context returns a Scheme object usually containing the high-level visual object's info- and control-structures. The Scheme object may be an environment/context in which info- and control-structures for visualization are defined. A visual object's control-structures are different from a programming language's control-structures. The former are only a kind of data structures. With the availability of GUILE modules, this function is almost obsolete. However, the VOML compiler uses vo-write-context to store a list of pair of the form '(record-type . event-type), for all data events recognized by the visual object, into this Scheme object. Based on this information, a dispatcher function may decide whether to call a VOML-generated VO's event-processing method. (set! context (vo-read-context vo)) reads the contents of the context object of visual object vo and stores it in variable context. vo-write-context Stores a Scheme object into a visual object. (vo-write-context visual-object context-object) visual-object Specifies the visual object into which to store the Scheme object. context-object Specifies the Scheme object to be stored into the visual object. vo-write-context updates the high-level visual object's associated Scheme object with context-object and returns the same Scheme object. With the availability of GUILE modules, this function is almost obsolete. However, the VOML compiler uses it to store a list of pair of the form '(record-type . event-type), for all data events recognized by the visual object, into this Scheme object. Based on this information, a dispatcher function may decide whether to call a VOML-generated VO's event-processing method. (vo-write-context vo (vector 0 0 0 0 0 0 (make-vector 41 0) 0 (make-vector 41 0))) writes a vector, some of whose elements are vectors themselves, to the context object of the visual object vo. vo-process-event Parses fields of an event trace record and updates info structures of a visual object. (vo-process-event visual-object event-info) visual-object Specifies the visual object. event-info Data representing an event to be processed by the visual object. May be of any type and it is up to the visual object to recognize it. vo-process-event is a method of the high-level visual object that calls the user-defined Scheme procedure for processing the event data and updates its info- and control-structures. The user-defined Scheme procedure should return 1 if sucessful. In the asynchronous visualization mode, the user-defined Scheme procedure should call the user-defined Scheme procedure for the rendering of the high-level visual object's info structures, immediately upon updating them. Otherwise, the user-defined Scheme procedure for the rendering of the info-structures will be called from elsewhere, when synchronization conditions are satisfied. In this example, the second argument to vo-process-event is an XDR data structure received from the JEWEL distributed instrumentation system. This is just to illustrate how complex data structures may be passed to visual objects; usually, the second argument to vo-process-event is a list. The JEWEL &PGRT;-TIE extension is not documented in this reference manual. (vo-process-event vo (_mdr_data_part.vd_data-ref (mdr_t.mdr_data_part-ref jewel-gps-ri-recv-msg))) vo-draw-info Renders the contents of info structures of a visual object in the visual object's view windows. (vo-draw-info visual-object) visual-object Specifies the visual object. vo-draw-info is a method of the high-level visual object which calls the user-defined Scheme procedure that renders the contents of its info-structures. The user-define Scheme procedure should return 1 if sucessful. In the asynchronous mode, vo-draw-info is called immediately after processing an event. In the synchronous mode, rendering in one or more visual objects/views is synchronized, and vo-draw-info is called for all these visual objects when synchronization conditions are satisfied. (vo-draw-info vo) calls the information rendering method of visual object vo. The responsibilities of a LLVO class described below (refer to ) illustrate the basic building block of the performance-visualization technology. The LLVO class maintains a number of display areas, referred to as views. In the X library implementation of the LLVO class, each display area is supported by a contained object that maintains the state of the corresponding X window. The LLVO class provides methods for rendering simple graphical objects, text and figures in the views. The coordinate system used for the graphical objects' representative coordinates (as arguments to the methods) is a world coordinate system specified by the user at the moment of (re)initializing a view. A view consists of an internal area surrounded by marings, referred to as scrollable area. As a visualization progresses, the mapping from the world coordinate system to the view coordinate system may change, at which point only the contents of the scrollable area may be translated or rescaled (zoomed) as a response. Methods such as vo-scroll, vo-resize, vo-rescale and vo-take-snapshot provide explicit control over each view. Combined with the graphical primitives, they allow a HLVO to control explicitly, among other things, what to be drawn and what to be visible at a point in time. A relation between a view and graphical primitives that draw in the view may be established that causes the view to adapt dynamically by translating or rescaling (zooming) the contents of the scrollable area, thus implicitly controlling what should be visible over an interval or time. The LLVO class may be portable to multiple graphical platforms that differ at some extent (e.g., different X servers may use different color maps). At run time, it may adapt to the platform capabilities, as well as provide a drawing optimization. vo-open Opens a view window of a visual object. (vo-open visual-object view-id) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. vo-open opens the window of the specified view of the specified visual object. Returns 1 if successful. Drawing is not affected by whether a view window is opened or closed. (vo-open gantt 0) opens the first (i.e., the one indexed by 0) view's window of visual object kept in variable gantt. vo-close Closes a view window of a visual object. (vo-close visual-object view-id) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. vo-close closes the window of the specified view of the specified visual object. Returns 1 if successful. Drawing is not affected by whether a view window is opened or closed. (vo-close gantt 0) closes the first (i.e., the one indexed by 0) view's window of visual object stored in variable gantt. vo-refresh Allows for maintenance of the low-level visual object view windows. (vo-refresh) None. vo-refresh is a method of the low-level visual object class implementation whose purpose is to refresh the windows of all active visual objects' views. A call to this procedure is supposed to be placed in an event loop (e.g., in the main event loop of the application). Returns #t. The Xlib low-level visual object class implementation of this method refreshes the contents of X windows within the application's context and also calls Tk_DoOneEvent(). Thus, if the application has a Tk-based GUI, separate calls to tk-do-one-event are not necessary. The following is the skeleton of a loop that refreshes the contents of all visual objects' views in each iteration. (let loop (...) (vo-refresh) ...) vo-get-view-info Obtains information about a view window of a visual object. (vo-get-view-info visual-object view-id) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. vo-get-view-info returns a list of 15 data about the state of a view window of a visual object. These data are (in this order): [0] mouse button number, [1] mouse cursor world x coordinate, [2] mouse cursor world y coordinates, [3] the last key pressed, [4] the color of the pixel under the mouse cursor, [5] the width of the view window in pixels, [6] the height in pixels, [7] the world x coordinate of the left edge of the view window, [8] the world y coordinate of the bottom edge of the view window, [9] the world x coordinate of the right edge of the view window, [10] the world y coordinate of the top edge of the view window, and the world dimensions of the [11] top, [12] right, [13] bottom, and [14] left margin, respectively. None. The following example shows how one can obtain the number of the last mouse button pressed over the first (i.e., the one indexed by 0) view of visual object vo. (let* ((winfo (vo-get-view-info vo 0)) (button-number (list-ref winfo 0)) ...) ...) vo-take-snapshot Takes a snapshot of a view window of a visual object and stores it into a GIF file. (vo-take-snapshot visual-object view-id filename) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. filename The name of the GIF file into which the snapshot is to be stored. The extension `.gif' is not assumed. vo-take-snapshot takes the current contents of the view window, converts it into the GIF image format and writes it to a (possibly newly created) file with the given name. Returns #t if successful; otherwise, it returns #f. None. (vo-take-snapshot vo 0 "snap.gif") takes a snapshot of the first (i.e., the one indexed by 0) view window of visual object vo and stores it in file snap.gif in GIF87 format. vo-scroll Scrolls the scrollable area of a visual object's view window. (vo-scroll visual-object view-id value direction) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object whose window's contents of the scrollable area is to be scrolled. value A real number that is the value to which the x or y coordinate of the edge of the scrollable area opposite to direction is set. direction One of the four integer constants: LEFT, RIGHT, UP, and DOWN. vo-scroll scrolls the contents of the scrollable area of the specified view window of the specified visual object, so that the world coordinate of the appropriate edge of the scrollable area becomes equal to value. To achieve "unnatural" scrolling to the right or up, consecutive values should form a non-increasing sequence. If this is inconvenient, reversing the sign of "normal," non-decreasing values should work, too. If the sequence of values is not monotonic, "jumping" forward and backward of the contents of the scrollable area is prevented, i.e., values which would cause scrolling in the direction opposite to direction are ignored.. The following call will result in the right edge of the scrollable area (of the 2nd view window of the visual object vo) be positioned at the world x coordinate 45.3. (vo-scroll vo 2 45.3 LEFT) vo-draw-point Draws a point in a visual object's view window. (vo-draw-point visual-object view-id x-coord y-coord color adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. x-coord A real number, the world x coordinate of the point. y-coord A real number, the world y coordinate of the point. color A string, the color of the point. adapt A Boolean that specifies whether the point is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the point is the scrollable area (#t) or the whole window (#f). vo-draw-point draws a point with specified parameters. If the point's location is beyond the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the point will be drawn visible. If the point's location is beyond the scrollable area, after the effect of the value of adapt, and the value of clip is #t, the point will not be drawn; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. The following call will draw a cyan point with world coordinates (x, y) = (5, 7). (vo-draw-point vo 0 5 7 "cyan" #f #f) vo-draw-line Draws a line in a visual object's view window. (vo-draw-line visual-object view-id x1 y1 x2 y2 thickness color adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. x1 A real number, the world x coordinate of the first end-point of the line. y1 A real number, the world y coordinate of the first end-point of the line. x2 A real number, the world x coordinate of the second end-point of the line. y2 A real number, the world y coordinate of the second end-point of the line. thickness A non-negative integer, the thickness of the line in pixels. color A string, the color of the line. adapt A Boolean that specifies whether the line is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the line is the scrollable area (#t) or the whole window (#f). vo-draw-line draws a line with specified parameters. If the line exceeds the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the line will be drawn fully visible. If the line exceeds the scrollable area after the effect of adapt, and the value of clip is #t, the line will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. The following call will draw a green line with world coordinates of its end-points (x1, y1) = (1, 1) and (x2, y2) = (5, 7). (vo-draw-line vo 2 1 1 5 7 "green" #f #f) vo-draw-rectangle Draws a rectangle in a visual object's view window. (vo-draw-rectangle visual-object view-id x1 y1 x2 y2 color fill-color adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. x1 A real number, the world x coordinate of the first corner of the rectangle. y1 A real number, the world y coordinate of the first corner of the rectangle. x2 A real number, the world x coordinate of the diagonally-opposite corner of the rectangle. y2 A real number, the world y coordinate of the diagonally-opposite corner of the rectangle. color A string, the color of the rectangle's border. fill-color A string, the color of the rectangle's inside. adapt A Boolean that specifies whether the rectangle is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the rectangle is the scrollable area (#t) or the whole window (#f). vo-draw-rectangle draws a rectangle with specified parameters. If the rectangle exceeds the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the rectangle will be drawn fully visible. If the rectangle exceeds the scrollable area after the effect of adapt, and the value of clip is #t, the rectangle will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. The following call will draw a rectangle with red border, green inside, and world coordinates of its diagonally-opposite corners (x1, y1) = (1, 1) and (x2, y2) = (5, 7). (vo-draw-rectangle vo 2 1 1 5 7 "red" "green" #f #t) vo-draw-polygon Draws a polygon in a visual object's view window. (vo-draw-polygon visual-object view-id points color fill-color adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. points A list of real numbers, world x-y coordinates of points that determine the polygon. color A string, the color of the polygon's border. fill-color A string, the color of the polygon's inside. adapt A Boolean that specifies whether the polygon is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the polygon is the scrollable area (#t) or the whole window (#f). vo-draw-polygon draws a polygon with specified parameters. If the polygon exceeds the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the polygon will be drawn fully visible. If the polygon exceeds the scrollable area after the effect of adapt, and the value of clip is #t, the polygon will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. The following call will draw a triangle with red border, green inside, and world coordinates of the points that determine it: (0, 0), (2, 0), and (1, 1). (vo-draw-polygon vo 0 '(0 0 2 0 1 1) "red" "green" #f #f) vo-draw-arc Draws an arc in a visual object's view window. (vo-draw-arc visual-object view-id x y radx rady start-angle end-angle angle color fill-color adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. x A real number, the world x coordinate of the center of the arc. y A real number, the world y coordinate of the center of the arc. radx A real number, the length of the first radius of the arc (i.e., the corresponding ellipse) in world dimensions. rady A real number, the length of the second radius of the arc (i.e., the corresponding ellipse) in world dimensions. start-angle A real number, the starting angle of the arc in radians. end-angle A real number, the ending angle of the arc in radians. angle A real number, the offset angle of the arc in radians. The start-angle and end-angle determine which part of the corresponding ellipse will the arc be, while angle determines the angle between the corresponding ellipse's first radius and x axis. (not implemented yet) color A string, the color of the arc's border. fill-color A string, the color of the arc's inside. adapt A Boolean that specifies whether the arc is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the arc is the scrollable area (#t) or the whole window (#f). vo-draw-arc draws an arc with specified parameters. If the arc exceeds the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the arc will be drawn fully visible. If the arc exceeds the scrollable area after the effect of adapt, and the value of clip is #t, the arc will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. The following call will draw an arc with red border, green inside, starting angle 0, ending angle pi/2, offset angle pi/4, radii 3 and 2, and center at (0, 0). (vo-draw-arc vo 1 0 0 3 2 0 (/ pi 2) (/ pi 4) "red" "green" #f #f) vo-draw-ellipse Draws an ellipse in a visual object's view window. (vo-draw-ellipse visual-object view-id x y radx rady angle color fill-color adapt clip) visual-object Specifies the visual object. win-id A non-negative integer that specifies the view of the visual object. x A real number, the world x coordinate of the center of the ellipse. y A real number, the world y coordinate of the center of the ellipse. radx A real number, the length of the first radius of the ellipse in world dimensions. rady A real number, the length of the second radius of the ellipse in world dimensions. angle A real number, the offset angle of the ellipse in radians. It is the angle between the ellipse's first radius and x axis. (not implemented yet) color A string, the color of the ellipse's border. fill-color A string, the color of the ellipse's inside. adapt A Boolean that specifies whether the ellipse is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the ellipse is the scrollable area (#t) or the whole window (#f). vo-draw-ellipse draws an ellipse with specified parameters. If the ellipse exceeds the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the ellipse will be drawn fully visible. If the ellipse exceeds the scrollable area after the effect of adapt, and the value of clip is #t, the ellipse will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. The following call will draw an ellipse with red border, green inside, offset angle pi/4, radii 3 and 2, and center at (0, 0). (vo-draw-ellipse vo 1 0 0 3 2 (/ pi 4) "red" "green" #f #f) vo-draw-text Draws a text in a visual object's view window. (vo-draw-text visual-object view-id text x y x-align y-align foreground background font adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. text A string, the text to be displayed. x A real number, the world x coordinate of the text's origin. y A real number, the world y coordinate of the text's origin. x-align An integer, one of the three constants: LEFT (default), RIGHT, and CENTER, specifying the horizontal alignment of the text. y-align An integer, one of the two constants: BOTTOM (default) and TOP, specifying the vertical alignment of the text. foreground A string, the foreground color of the text. background A string, the background color of the text. font A string, the X11 font name of the font used to render the text. adapt A Boolean that specifies whether the text is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the text is the scrollable area (#t) or the whole window (#f). vo-draw-text draws a text with specified parameters. If the text exceeds the area displayed in the view window's canvas and the value of adapt is #t, the view window will first adapt by rescaling the contents of its canvas in the appropriate direction and then the text will be drawn fully visible. If the text exceeds the scrollable area after the effect of adapt, and the value of clip is #t, the text will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. None. (vo-draw-text vo 1 "Hello, world!" 100.0 0.0 "black" "white" "fixed" LEFT BOTTOM #f #f) writes string Hello, world! using pretty standard parameters, with its left-bottom point at world coordinates (100, 0). vo-draw-figure Extract and copies a scaled portion of a GIF image to a view window of a visual object. (vo-draw-figure visual-object view-id filename orig-x-offset orig-y-offset orig-width orig-height world-x-offset world-y-offset world-width world-height adapt clip) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. filename The name of the GIF file. orig-x-offset The x offset in pixels of the subimage to be extracted (a non-negative integer). orig-y-offset The y offset in pixels of the subimage to be extracted (a non-negative integer). orig-width The width in pixels of the subimage to be extracted (a non-negative integer). Zero width means the whole width. orig-height The height in pixels of the subimage to be extracted (a non-negative integer). Zero height means the whole height. world-x-offset The world x coordinate of the lower left corner of the subimage in the view window. world-y-offset The world y coordinate of the lower left corner of the subimage in the view window. world-width The width, in the world coordinate system, of the subimage in the view window. Zero width means no rescaling horizontally. world-height The height, in the world coordinate system, of the subimage in the view window. Zero height means no rescaling vertically. adapt A Boolean that specifies whether the figure is important for the visual object dynamic adaptation. clip A Boolean that specifies whether the allowed rectangle area for drawing the figure is the scrollable area (#t) or the whole window (#f). vo-draw-figure extracts a (rectangular) subimage, given by the offset (orig-x-offset and orig-y-offset) and dimensions (orig-width and orig-height, if non-zero) from a GIF file. Then, it rescales the subimage so that its dimensions in the world coordinate system of the given view window are world-width and world-height (if non-zero), and copies it to the view window, using world-x-offset and world-y-offset as the coordinates of the lower left corner. None. The following call will extract a rectangular figure from GIF file "logo.gif", with the lower left corner at (10, 10) and upper right corner at (30, 50); then it will rescale it so that its dimensions in the world coordinate system of the view window are 15.5 by 15.5, and copy it so that its lower left corner is placed at (100.0, 20.0) in the world coordinate system. If the figure would exceed the scrollable area, then the world coordinate system will be made to adapt, according to the view's dynamic adaptation, so that the figure fits into the scrollable area afterwards. If the figure exceeds the scrollable area after the effect of adapt, and the value of clip is #t, it will be clipped-off at the margins; otherwise, it will be drawn, even beyond the scrollable area. Returns 1 if successful. (vo-draw-figure vo 0 "logo.gif" 10 10 20 40 100.0 20.0 15.5 15.5 #t #f) vo-resize Resizes a view window of a visual object. (vo-resize visual-object view-id new-width new-height) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. new-width The new width of the view window in pixels. new-height The new height of the view window in pixels. vo-resize resizes the view window so that its new dimensions in pixels become new-width by new-height. The contents of the window is appropriately rescaled. Returns 1 if successful. None. In this example, the view window is resized to become 150 pixels wide and 150 pixels high, and the graphical contents is resized appropriately. The world coordinate system is not affected. (vo-resize vo 0 150 150) vo-rescale Rescales the scrollable area of a view window of a visual object. (vo-rescale visual-object view-id x-factor y-factor) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. x-factor The factor by which the ratio world / window x coordinate is multiplied. If x-factor is greater than 1, the contents of the window becomes "smaller." If x-factor is positive, the reference (static) edge is the left edge of the scrollable area; if it is negative, the reference edge is the right edge of the scrollable area, and the absolute value of x-factor is used for rescaling. y-factor The factor by which the ratio world / window y coordinate is multiplied. If y-factor is greater than 1, the contents of the window becomes "smaller." If y-factor is positive, the reference (static) edge is the bottom edge of the scrollable area; if it is negative, the reference edge is the top edge of the scrollable area, and the absolute value of y-factor is used for rescaling. vo-rescale rescales the contents of the scrollable area of the view window and establishes new ratios between the world and window coordinates (which hold not only for the scrollable area but for the whole window). The graphical contents in the margins is not rescaled. Returns 1 if successful. None. In this example, the graphical contents of the 0th view window of the visual object vo is horizontally shrunk by 50% (with the left edge of the scrollable area being the reference edge) vertically stretched by 100% (with the bottom edge of the scrollable area being the reference edge). (vo-rescale vo 0 2.0 0.5) vo-postpone Toggles postponed drawing to a view window. (vo-postpone visual-object view-id flag) visual-object Specifies the visual object. view-id A non-negative integer that specifies the view of the visual object. flag Turns on (when #t) or off (when #f) the postponed drawing to the view window. To avoid flickering, it is sometimes better to first draw several graphical objects to memory, and then copy the whole graphical contents to the view window. The drawing only to memory is called postponed, and is turned on by calling vo-postpone with flag set to #t. When the graphical contents is to be copied to the view window, vo-postpone should be called with flag set to #f. The function returns 1. None. (vo-postpone vo 0 #t) postpones drawing to the first (i.e., the one indexed by 0) view window of visual object vo. From this point on, graphical objects will only be drawn in memory belonging to this view. vo-text-extents Returns the rectangle extents that a text string occupies. (vo-text-extents text font x-align y-align) text The text whose extents is to be computed. font The font assumed when computing the text extents. x-align The horizontal alignment assumed when computing the text extents. y-align The vertical alignment assumed when computing the text extents. vo-text-extents does not apply to a specific view or visual object. Given a text string and a font name, it returns a list of four numbers determining the rectangle area (min x, min y, max x, max y) occupied by the text, with its lower-left pixel positioned at (0, 0). To obtain these numbers, the left and right text bearings are taken into account, as well as the horizontal alignment x-align, so that some of the number may be negative. Similarly, the text ascent and descent are taken into account, together with the vertical alignment y-align. When aligning horizontally, bearings are used in the offset computation, so that different text strings may have different offsets in order for their extreme points to be aligned. The vertical alignment works a little differently: the text descent is not used when the alignment is BOTTOM; instead, text strings are aligned by their baseline. When the vertical alignment is TOP, the y coordinate of a text string is decreased by the corresponding text ascent. The call below returns '(0 -2 48 11). (vo-text-extents "Michigan" "fixed" LEFT BOTTOM) When the vertical alignment is changed to TOP, the call returns '(0 -13 48 1). Similarly, when the horizontal alignment is changed to RIGHT, the call returns '(-47 2 1 11). Two functions are defined in module (pgrt vo) that are used by code generated by the VOML compiler to support higher-level behavior of info-structure rendering (IR) components. vo-undraw-irc Undraws graphical objects previously drawn by an IR component. (vo-undraw-irc vo bag mode) vo A visual object. bag A list of vectors that contain information about calls to graphical primitives in previous invocations of an IR component. mode An additional parameter to control the way undrawing is done. Currently ignored. Visual object code generated by the VOML compiler may contain IR bags to store information about graphical objects drawn by individual IR components. These are lists of vectors containing all the arguments of calls to graphical primitives (see the section on low-level visual object functions), in the same order, plus a background color to be used when undrawing a graphical object, as the last element of each such vector. The first element of a bag contains information about each view to which the IR component draws, obtained using vo-get-view-info at the end of the IR component. vo-undraw-irc first obtains the current information about the above views, and computes the difference from the information stored in bag that is due to scrolls and/or rescalings of the views' coordinate systems since the last time the IR was called. Using the difference, vo-undraw-irc tries to account for possible rounding errors in scrolls/rescalings that could have resulted is bad-looking content in raster-based views. Similarly, vo-undraw-irc uses clipping information to undraw graphical objects that were drawn in margins. vo-undraw-irc returns an empty bag (list). vo-undraw-irc cannot handle correctly graphical objects that span both the scrollable area and margins, because only the content of the scrollable area is affected by scrolls and rescalings. (set! ircbag-IRANIMCOMM (vo-undraw-irc vo ircbag-IRANIMCOMM 'update)) The above code is generated by the VOML compiler at the beginning of IR component IRANIMCOMM, whose refresh attribute has value of update. vo-redraw-irc Redraws graphical objects previously drawn by an IR component. (vo-redraw-irc vo bag mode) vo A visual object. bag A list of vectors that contain information about calls to graphical primitives in previous invocations of an IR component. mode An additional parameter to control the way undrawing is done. Distinguished values are symbols rescale and resize. vo-redraw-irc first calls vo-undraw-irc passing to it its own parameters, and then redraws graphical objects from bag. Parameter mode affects the use of the adaptation flag when drawing the graphical objects. vo-redraw-irc returns bag. vo-redraw-irc cannot handle correctly graphical objects that span both the scrollable area and margins, because only the content of the scrollable area is affected by scrolls and rescalings. (set! ircbag-IRANIMCOMM (vo-redraw-irc vo ircbag-IRANIMCOMM 'resize))) The above code is generated by the VOML compiler within the callback method when the refresh attribute of IRANIMCOMM IR component contains resize. CENTER Has the value of integer 4. Used in text alignment. RIGHT Has the value of integer 0. Used in text alignment and scrolling. DOWN Has the value of integer 3. Used in scrolling and text alignment. BOTTOM A synonym for DOWN. LEFT Has the value of integer 2. Used in text alignment and scrolling. UP Has the value of integer 1. Used in scrolling and text alignment. TOP A synonym for UP. XPLUS.R or XPLUS Has the value of integer 1. Used in visual object initialization, in the visual object dynamic adaptation. Triggers rescaling to include important graphical objects with x coordinates greater than that of the right edge of the scrollable area. XMINUS.R or XMINUS Has the value of integer 4. Used in visual object initialization, in the visual object dynamic adaptation. Triggers rescaling to include important graphical objects with x coordinates less than that of the left edge of the scrollable area. YPLUS.R or YPLUS Has the value of integer 8. Used in visual object initialization, in the visual object dynamic adaptation. Triggers rescaling to include important graphical objects with y coordinates greater than that of the top edge of the scrollable area. YMINUS.R or YMINUS Has the value of integer 2. Used in visual object initialization, in the visual object dynamic adaptation. Triggers rescaling to include important graphical objects with y coordinates less than that of the top edge of the scrollable area. XPLUS.S Has the value of integer 16. Used in visual object initialization, in the visual object dynamic adaptation. Triggers scrolling to the left to include important graphical objects with x coordinates greater than that of the right edge of the scrollable area. XMINUS.S Has the value of integer 64. Used in visual object initialization, in the visual object dynamic adaptation. Triggers scrolling to the right to include important graphical objects with x coordinates less than that of the left edge of the scrollable area. YMINUS.S Has the value of integer 32. Used in visual object initialization, in the visual object dynamic adaptation. Triggers scrolling up to include important graphical objects with y coordinates less than that of the bottom edge of the scrollable area. YPLUS.S Has the value of integer 128. Used in visual object initialization, in the visual object dynamic adaptation. Triggers scrolling down to include important graphical objects with y coordinates greater than that of the top edge of the scrollable area. EVENT_CLICK Has the value of integer 1. In the user-defined Scheme callback procedure, used to check, by comparing with one of the procedure's parameters, whether the callback occurred due to a mouse click. EVENT_KEYSTROKE Has the value of integer 2. In the user-defined Scheme callback procedure, used to check, by comparing with one of the procedure's parameters, whether the callback occurred due to a keyboard stroke. EVENT_RESIZE Has the value of integer 3. In the user-defined Scheme callback procedure, used to check, by comparing with one of the procedure's parameters, whether the callback occurred due to resizing of the contents of a visual object's view window. EVENT_RESCALE Has the value of integer 4. In the user-defined Scheme callback procedure, used to check, by comparing with one of the procedure's parameters, whether the callback occurred due to rescaling of the contents of a visual object's view window (more precisely, the contents of the scrollable area). ENTRY Has the value of integer 3. Used to denote an entry PICL record. EXIT Has the value of integer 4. used to denote an exit PICL record. PG-ENTRY Has the value of integer -3. Used to denote an entry PICL record as understood by the ParaGraph tool. PG-EXIT Has the value of integer -4. Used to denote an exit PICL record as understood by the ParaGraph tool. lt The same as function <, but more convenient for embedding in VOML code. gt The same as function >, but more convenient for embedding in VOML code. lte The same as function <=, but more convenient for embedding in VOML code. gte The same as function >=, but more convenient for embedding in VOML code. (use-modules (pgrt corba)) The Visual Objects CORBA interface includes an ORB within &PGRT;-TIE and an interface for registering visual objects with the ORB. The CORBA interface is used to receive event records from an instrumentation system via CORBA calls and pass them to visual objects running within the run-time environment. For each visual object, there is a front-end object defined in CORBA IDL. orb-init Creates and starts the ORB. (orb-init orb-address ns-address) orb-address A string obeying one of the three address formats defined by the MICO implementation of CORBA 2.0, internet address, unix address, or local address, used to denote the ORB address (the MICO -ORBIIOPAddr option). In general, the internet address format is inet:<host name>:<port number> and refers to the process running on machine <host name> that owns the TCP port <port number>. The unix address format is unix:<socket file name> and refers to the process running on the current machine that owns the unix-domain socket bound to <socket file name>. The local address format is local: and refers to the process it is used in (i.e., this process). ns-address A string obeying one of the three address formats explained above, used to denote the address of the CORBA name service (the MICO -ORBNamingAddr option). orb-init creates an ORB within the run-time environment. If successful, it returns #t. If no name service daemon is found, it returns #f. Neither orb-address nor ns-address can be an empty string. (orb-init "inet:lithium:55556" "inet:californium:55555") initializes the ORB on machine lithium so that it accepts requests at port 55556 and assumes that the name service daemon is runnin on machine californium and accepts requests at port 55555. orb-check Checks for incoming ORB requests. (orb-check block) block An integer specifying whether to block while checking for incoming requests. Ignored in the current implementation. Since MICO is not multithreaded, orb-check need be called from time to time, in order to check for incoming ORB requests (each call to orb-check allows the ORB to process the incoming requests). This will typically be done within a loop, which in turn may be within a GUILE (Scheme) thread. The block is aimed for future use, when MICO design settles. orb-check returns #t if an ORB is running; otherwise, it returns #f. None. (orb-check 0) allows the ORB to check for incoming requests. register-vo-with-orb Registers indirectly a visual object with the ORB. (register-vo-with-orb name visual-object) name A string, the name for the CORBA name service. visual-object The visual object to be bound to the CORBA object receiving event processing requests through the ORB. register-with-orb creates a CORBA object that acts on behalf of visual-object, and registers it with the name service. The kind of the CORBA object is "PGRTVO", and its name is name. In the current implementation, the CORBA object only enqueues requests for visual-object (i.e., instrumentation data records to be passed to its process-event method) into a queue shared by all registered visual objects. This is to avoid blocking of the instrumentation system by visual objects processing the instrumentation data records. If an ORB is running, register-with-orb returns #t; otherwise, it returns #f. None. (register-with-orb "gantt" gantt) where gantt is a visual object. corba-check Checks for pending calls to visual objects' process-event methods. (corba-check) None. corba-check returns #t if there are instrumentation data records (for any visual object) pending in the queue. Otherwise, it returns #f. None. (corba-check) checks if there are pending instrumentation data records for visual objects. corba-receive Returns a list of instrumentation data records, paired with their destined visual objects. (corba-receive) None. corba-receive returns a list of pairs (possibly empty). Each pair is of the form (visual-object . event), where visual-object is the destined visual object of the instrumentation data record event. None. (let ((newly-arrived-events (corba-receive))) (alist-for-each (lambda (vo event) (process-event vo event)) newly-arrived-events)) shows how instrumentation data records, which have arrived via the CORBA interface, can be passed to visual object vo. Currently, only one utility function is defined in module (pgrt corba). corba-recv-a-session A receive-then-process loop. (corba-recv-a-session) None. The code of function corba-recv-a-session and definitions of relevant variables are presented that combines several primitives described in this chapter. corba-recv-a-session is a public function defined in module (pgrt corba). When called, it creates a thread that receives instrumentation data records via the CORBA interface and passes them to visual objects in vo-list for processing until end-of-session is set to a non-#f value. (define-public corba-mu (make-mutex)) (define-public corba-condvar (make-condition-variable)) (define-public corba-recv-a-session (lambda () (make-thread (let loop () (if (not end-of-session) (begin (wait-condition-variable corba-condvar corba-mu) (alist-for-each (lambda (vo trec) (vo-process-event vo trec)) (corba-receive)) (loop))))))) Variables corba-mu and corba-condvar are used together by wait-condition-variable to implement the semantics of the needed synchronization. None. Concurrently with the above defined thread, there need be another thread that will periodically execute code similar to the following (orb-check 0) (if (corba-check) (signal-condition-variable corba-condvar)) to notify the thread when there are instrumentation data records to be received via the CORBA interface. Each received instrumentation data record is subsequently passed to its destined visual object. corba-condvar A condition variable used in corba-recv-a-sesison. corba-mu A mutex used in conjunction with corba-condvar. (use-modules (pgrt brisk)) The BRISK support includes an interface for receiving instrumentation data records and procedures for passing them to visual objects. This section describes primitives that implement the interface between the BRISK distributed instrumentation system and the &PGRT; tool integration environment. brisk-init Initializes the BRISK interface. (brisk-init) None. A call to this function allocates and attaches the shared memory segment that contains a ring buffer with instrumentation data records written by the BRISK ISM. If successful, returns #t; otherwise, it returns #f. None. (brisk-init) establishes a shared-memory connection with the BRISK ISM. brisk-check Checks for BRISK instrumentation data records. (brisk-check) None. brisk-check returns #t if there are instrumentation data records to be receiveded from BRISK ISM. Otherwise, it returns #f. If the BRISK ISM shared memory buffer has not been allocated (e.g., if brisk-init failed), brisk-check returns #f. (brisk-check) checks if there are instrumentation data records pending in the shared memory buffer. brisk-receive Returns (at most) one instrumentation data record from the ring buffer. (brisk-receive ts-flag) ts-flag An integer that specifies whether the time-stamp is taken from BRISK (an UTC integer, when ts-flag equals 0) or is computed as the number of seconds after the call to brisk-init. brisk-receive returns a list of instrumentation data record fields, if successful; otherwise, it returns #f. The parameter ts-flag specifies the time-stamp format, which is important only when the instrumentation data record returned has the time-stamp as one of its fields. None. (brisk-receive 0) returns an instrumentation data record from the shared memory buffer, if found. Currently, only one utility function is defined in module (pgrt brisk). brisk-recv-a-session A receive-then-process loop. (brisk-recv-a-session) None. The code of function brisk-recv-a-session and definitions of relevant variables are presented that combines several primitives described in this chapter. brisk-recv-a-session is a public function defined in module (pgrt brisk). When called, it creates a thread that receives instrumentation data records from the BRISK instrumentation system and passes them to visual objects in vo-list for processing until end-of-session is set to a non-#f value. (define-public brisk-mu (make-mutex)) (define-public brisk-condvar (make-condition-variable)) (define-public brisk-recv-a-session (lambda (ts-format) (make-thread (lambda () (let loop () (if (not end-of-session) (begin (wait-condition-variable brisk-condvar brisk-mu) (let loop2 ((trec (brisk-receive ts-format))) (if (and trec (not (null? trec))) (begin (for-each (lambda (vo) (vo-process-event vo trec)) vo-list) (loop2 (brisk-receive ts-format))))) (loop)))))))) Variables brisk-mu and brisk-condvar are used together by wait-condition-variable to implement the semantics of the needed synchronization. None. Concurrently with the above defined thread, there need be another thread that will periodically execute the following code (if (brisk-check) (signal-condition-variable brisk-condvar)) to notify the thread when there are instrumentation data records to be received by BRISK ISM. Each received instrumentation data record is subsequently passed to all visual objects in vo-list. brisk-condvar A condition variable used in brisk-recv-a-session. brisk-mu A mutex used in conjunction with brisk-condvar. (use-modules (pgrt xdr)) XDR routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls (RPC) are transmitted using these routines. The &PGRT;-TIE XDR support implements a Scheme interface to a majority of the XDR routines, so that the data structures can be exchanged between C and Scheme programs. The XDR support includes low-level XDR functions and an XDR to Scheme translator, written by Aleksandar Bakić. See also XDR man pages. These functions deal with the creation of XDR streams. XDR streams have to be created before any data can be translated into XDR format. In &PGRT;-TIE, every XDR stream is represented by a Scheme XDR object. xdrmem-create Creates an XDR stream object in memory. (xdrmem-create data-info x-op) data-info A pair containing the address and size in bytes of an in-memory buffer. x-op The XDR operation type. If successful, xdrmem-create returns a Scheme XDR object that corresponds to the XDR stream with the given in-memory buffer. If the XDR operation type is XDR_ENCODE, the first element of data-info (the buffer address) is ignored. Otherwise, it returns #f. xdrmem-create allocates space for both the XDR stream and in-memory buffer. In order to send/receive data stored in the in-memory buffer, one needs functions that can access the buffer, given its address, and write/read from it. Usually, such functions belong to a GUILE extension. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) creates an in-memory XDR stream for encoding. xdrmem-get-data-info Returns a pair of an XDR stream's in-memory buffer address and size. (xdrmem-get-data-info xdr-object) xdr-object A Scheme XDR object. xdrmem-get-data-info is a utility function that returns a pair of an XDR stream's in-memory buffer address and size. The XDR stream corresponds to xdr-object. The result is valid only if xdrmem-get-data-info is applied on Scheme XDR objects that correspond to in-memory XDR streams. The last call in the following example may return (1043832 . 2048). The value of the first element of the returned pair depends on the memory-management system. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdrmem-get-data-info xdrobj) xdrmem-free Frees the memory used by an XDR stream. (xdrmem-free xdr-object) xdr-object A Scheme XDR object. There is no direct counterpart for xdrmem-free in the XDR library. This function is provided for convenience and to simplify the use of xdrmem-create. It frees the memory space used the XDR stream corresponding to xdr-object, and returns modified xdr-object, which has a fresh buffer for encoding or decoding. xdrmem-free creates a side-effect, i.e., changes data corresponding to xdr-object. (xdrmem-free xdrobj) frees (or clears) the in-memory buffer associated with XDR stream object xdrobj; the effect is similar to a new call to xdrmem-create. xdrmem-destroy Destroys an XDR stream and frees the memory it used. (xdrmem-destroy xdr-object) xdr-object A Scheme XDR object. xdrmem-destroy destroys the XDR stream corresponding to xdr-object and frees up the memory space it used. Returns xdr-object, which becomes unusable. xdrmem-destroy uses a side-effect, i.e., changes data corresponding to xdr-object. (xdrmem-destroy xdrobj) simply renders the XDR object stored in xdrobj unusable. These XDR functions allow Scheme programmers to describe simple data structures in a machine-independent fashion. They require the creation of XDR streams (see xdrmem-create). Unlike their C counterparts that use pointers to variables whose values are to be translated, these functions return translated values when the XDR operation type is XDR_DECODE. xdr-bool Translates between Scheme objects of type Boolean and their XDR representations. (xdr-bool xdr-object bool-obj) xdr-object A Scheme XDR object. bool-obj The Scheme Boolean to be translated from/to its XDR representation. If successful, xdr-bool returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to translate a Boolean to its XDR representation. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-bool xdrobj #t) xdr-char Translates between Scheme objects of type integer (exact in the range from -128 to 127) and their XDR representations as chars. (xdr-char xdr-object char-obj) xdr-object A Scheme XDR object. char-obj The Scheme bounded integer (exact) to be translated from/to its XDR representation as a char. If successful, xdr-char returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to obtain a Scheme integer (exact) from its XDR representation as a char. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is a char (define charobj #\Nul) (set! charobj (xdr-char xdrobj charobj)) The second argument to xdr-char in this example does not have to be the same as the variable being updated. However, the type of the second argument must be bounded integer (exact). xdr-double Translates between Scheme objects of type real and their XDR representations as doubles. (xdr-double xdr-object real-obj) xdr-object A Scheme XDR object. real-obj The Scheme real to be translated from/to its XDR representation as a double. If successful, xdr-double returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to translate a real to its XDR representation as a double. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-double xdrobj 123.45) xdr-enum Translates between Scheme objects of type positive integer (exact) and their XDR representations as enums. (xdr-double xdr-object enum-obj) xdr-object A Scheme XDR object. enum-obj The Scheme positive integer (exact) to be translated from/to its XDR representation as an enum. If successful, xdr-enum returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to translate an enum to its XDR representation. See also other examples in this section. (define RED 1) (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-enum xdrobj RED) xdr-float Translates between Scheme objects of type real (in the range from -MAXFLOAT to MAXFLOAT) and their XDR representations as floats. (xdr-float xdr-object float-obj) xdr-object A Scheme XDR object. float-obj The Scheme bounded real to be translated from/to its XDR representation as a float. If successful, xdr-float returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to obtain a Scheme bounded real from its XDR representation as a float. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is a float (define floatobj 0.0) (set! floatobj (xdr-float xdrobj floatobj)) The second argument to xdr-float in this example does not have to be the same as the variable being updated. However, the type of the second argument must be bounded real. xdr-hyper Translates between Scheme objects of type integer (exact) and their XDR representations as hypers (8-byte integers). (xdr-hyper xdr-object hyper-obj) xdr-object A Scheme XDR object. hyper-obj The Scheme integer (exact) to be translated from/to its XDR representation as a hyper. If successful, xdr-hyper returns the translated Scheme datum. Otherwise, it returns #f. Currently, hypers are translated to ordinary Scheme integers. Support for bignums is planned. This example shows how to translate an integer to its XDR representation as a hyper. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-hyper xdrobj 123) xdr-int Translates between Scheme objects of type integer (exact) (in the range from -MAXINT - 1 to MAXINT) and their XDR representations as ints. (xdr-int xdr-object int-obj) xdr-object A Scheme XDR object. int-obj The Scheme bounded integer (exact) to be translated from/to its XDR representation as an int. If successful, xdr-int returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to obtain a Scheme integer (exact) from its XDR representation as an int. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is an int (define intobj 0) (set! intobj (xdr-int xdrobj intobj)) The second argument to xdr-int in this example does not have to be the same as the variable being updated. However, the type of the second argument must be bounded integer (exact). xdr-long Translates between Scheme objects of type integer (exact) and their XDR representations as longs. (xdr-long xdr-object long-obj) xdr-object A Scheme XDR object. long-obj The Scheme integer (exact) to be translated from/to its XDR representation as a long. If successful, xdr-long returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to obtain a Scheme integer (exact) from its XDR representation as a long. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is a long (define longobj 0) (set! longobj (xdr-long xdrobj longobj)) The second argument to xdr-long in this example does not have to be the same as the variable being updated. However, the type of the second argument must be integer (exact). xdr-quad Translates between Scheme objects of type real and their XDR representations as quadruples (16-byte reals). (xdr-quad xdr-object quad-obj) xdr-object A Scheme XDR object. quad-obj The Scheme real to be translated from/to its XDR representation as a quadruple. If successful, xdr-quad returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to translate a real to its XDR representation as a quadruple. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-quad xdrobj 123.45) xdr-short Translates between Scheme objects of type integer (in the range from -MAXSHORT - 1 to MAXSHORT) and their XDR representations as shorts. (xdr-short xdr-object short-obj) xdr-object A Scheme XDR object. short-obj The Scheme bounded integer (exact) to be translated from/to its XDR representation as a short. If successful, xdr-short returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to obtain a Scheme bounded integer (exact) from its XDR representation as a short. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is a short (define shortobj 0) (set! shortobj (xdr-short xdrobj shortobj)) The second argument to xdr-short in this example does not have to be the same as the variable being updated. However, the type of the second argument must be bounded integer (exact). xdr-u_char Translates between Scheme objects of type integer (exact in the range from 0 to 255) and their XDR representations as unsigned chars. (xdr-u_char xdr-object u_char-obj) xdr-object A Scheme XDR object. u_char-obj The Scheme bounded integer (exact) to be translated from/to its XDR representation as an unsigned char. If successful, xdr-u_char returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to translate a bounded integer to its XDR representation as an unsigned char. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-u_char xdrobj 64) xdr-u_hyper Translates between Scheme objects of type non-negative integer and their XDR representations as unsigned hypers. (xdr-u_hyper xdr-object u_hyper-obj) xdr-object A Scheme XDR object. u_hyper-obj The Scheme non-negative integer (exact) to be translated from/to its XDR representation as an unsigned hyper. If successful, xdr-u_hyper returns the translated Scheme datum. Otherwise, it returns #f. Currently, unigned hypers are translated to ordinary Scheme integers. Support for bignums is planned. This example shows how to obtain a Scheme non-negative integer (exact) from its XDR representation as an unsigned hyper. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is an unsigned hyper (define u_hiperobj 0.0) (set! u_hyperobj (xdr-u_hyper xdrobj u_hyperobj)) The second argument to xdr-u_hyper in this example does not have to be the same as the variable being updated. However, the type of the second argument must be non-negative integer (exact). xdr-u_int Translates between Scheme objects of type non-negative integer (exact less than or equal to 2 * MAXINT + 1) and their XDR representations as unsigned ints. (xdr-u_int xdr-object u_int-obj) xdr-object A Scheme XDR object. u_int-obj The Scheme bounded non-negative integer (exact) to be translated from/to its XDR representation as an unsigned int. If successful, xdr-u_int returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to translate a non-negative bounded integer to its XDR representation as an unsigned int. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE) (xdr-u_int xdrobj 60000) xdr-u_long Translates between Scheme objects of type non-negative integer (exact) and their XDR representations as unsigned longs.. (xdr-u_long xdr-object u_long-obj) xdr-object A Scheme XDR object. u_long-obj The scheme non-negative integer (exact) to be translated from/to its XDR representation as an unsigned long. If successful, xdr-u_long returns the translated Scheme datum. Otherwise, it returns #f. None. This example shows how to obtain a Scheme non-negative integer (exact) from its XDR representation as an unsigned long. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next datum to be decoded is an unsigned long (define u_longobj 0) (set! u_longobj (xdr-u_long xdrobj u_longobj)) The second argument to xdr-u_long in this example does not have to be the same as the variable being updated. However, the type of the second argument must be non-negative integer (exact). xdr-u_short Translates between Scheme objects of type non-negative integer (exact less than or equal to 2 * MAXSHORT + 1) and their XDR representations as unsigned shorts. (xdr-u_short xdr-object u_short-obj) xdr-object A Scheme XDR object. u_short-obj The Scheme bounded non-negative integer (exact) to be translated from/to its XDR representation as an unsigned short. If successful, xdr-u_short returns the translated Scheme datum. Otherwise, it returns fff. None. This example shows how to translate a bounded non-negative integer (exact) to its XDR representation as an unsigned short. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-u_short xdrobj 15) xdr-void Does nothing and always returns #t. (xdr-void) None. xdr-void always returns #t. The corresponding XDR library function xdr_void() always returns TRUE. It may be passed to RPC routines that require a function parameter, where nothing is to be done. Hence, xdr-void always returns #t. (xdr-void) These XDR functions allow Scheme programmers to describe complex data structures in a machine-independent fashion. They require the creation of XDR streams (see xdrmem-create). Unlike their C counterparts that use pointers to variables whose values are to be translated, these functions return translated values when the XDR operation type is XDR_DECODE. Not all the XDR library functions for complex data have Scheme-primitive counterparts. Some of the Scheme complex data functions have been implemented as Scheme procedures. See also section on the XDR-to-Scheme translator. xdr-fix-string Translates between Scheme objects of type fixed-length string (representing also arrays of opaque data) and their XDR representations. (xdr-fix-string xdr-object string-obj string-len) xdr-object A Scheme XDR object. string-obj The Scheme string to be translated to/from its XDR representation as a fixed-length array of unsigned chars. string-len The length of string-obj. xdr-fix-string is used for both strings and opaque (byte) arrays of fixed length (stored in Scheme non-null-terminated strings). The length of string-obj must be equal to string-len. The implementation of xdr-fix-string uses XDR library function xdr_u_char() to directly translate from/to chars/bytes. It returns the translated Scheme datum if successful; otherwise, it returns #f. Currently, only 8-bit characters are supported. This example shows how to translate a Scheme fixed-length string to its XDR representation as four unsigned chars. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (xdr-fix-string xdrobj "1234" 4) xdr-var-string Translates between Scheme objects of type variable-length string (representing also arrays of opaque data) and their XDR representations. (xdr-var-string xdr-object string-obj max-string-len) xdr-object A Scheme XDR object. string-obj The Scheme string to be translated to/from its XDR representation as a variable-length array of unsigned chars. max-string-len The maximum length of string-obj. xdr-var-string is used for both strings and opaque (byte) arrays of variable, but bounded, length (stored in Scheme non-null-terminated strings). The length of string-obj must be less than or equal to max-string-len. The implementation of xdr-var-string uses XDR library function xdr_u_char() to directly translate from/to chars/bytes. It returns the translated Scheme datum if successful; otherwise, it returns #f. Currently, only 8-bit characters are supported. When decoding (i.e., translating from XDR representation), the resulting string has the same length as the XDR array to be decoded. This example shows how to obtain a Scheme variable-length string from its XDR representation as an variable-length array of chars/bytes. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next data to be decoded are an array of unsigned ; chars, at most 10 bytes long (define my-string " ") ; 10 characters (set! my-string (xdr-var-string xdrobj my-string 10)) The second argument to xdr-var-string in this example does not have to be the same as the variable being updated. However, the type of the second argument must be string of up to 10 characters. xdr-fix-array Translates between Scheme vectors of type fixed-length vector and their XDR representations. (xdr-fix-array xdr-object vec xdr-fun veltc-fun vec-len) xdr-object A Scheme XDR object. vec The Scheme vector to be translated to/from its XDR representation as a fixed-length array. xdr-fun A Scheme function that translates a datum of the same type as the elements of vec, to/from its XDR representation. veltc-fun A Scheme function that creates a datum of the same type as the elements of vec. vec-len The length of vec. xdr-fix-array is used for translating to and from XDR representation of a Scheme (homogeneous) vector vec whose elements are of type defined by the constructor function veltc-fun. Function xdr-fun is responsible for performing the translation of the given type. The length of vec must be equal to vec-len. If successful, xdr-fix-array returns the translated Scheme vector; otherwise, it returns #f. None. This example shows how to obtain a 10-element Scheme vector of bounded reals (floats) from its XDR representation as a 10-element array of floats. It is assumed that the data buffer address is known (#x1000000). See also other examples in this section, especially the one for xdr-var-array. (define xdrobj (xdrmem-create '(#x1000000 . 2048) XDR_DECODE)) (define (new-float) 0.0) (define vec (make-vector 10 (new-float))) ; fill in xdrobj's buffer with data in XDR format, ; assume that the next data to be decoded are a 10-element array of floats (set! vec (xdr-fix-array vec xdr-float new-float 10)) The second argument to xdr-fix-array in this example does not have to be the same as the variable being updated. However, the type of the second argument must be a 10-element vector of bounded reals (floats). xdr-var-array Translates between Scheme vectors of type variable-length vector and their XDR representations. (xdr-var-array xdr-object vec xdr-fun veltc-fun max-vec-len) xdr-object A Scheme XDR object. vec The Scheme vector to be translated to/from its XDR representation as a variable-length array. xdr-fun A Scheme function that translates a datum of the same type as the elements of vec, to/from its XDR representation. veltc-fun A Scheme function that creates a datum of the same type as the elements of vec. max-vec-len The maximum length of vec. xdr-var-array is used for translating to and from XDR representation of a Scheme (homogeneous) vector vec whose elements are of type defined by the constructor function veltc-fun. Function xdr-fun is responsible for performing the translation of the given type. The length of vec must be less than or equal to max-vec-len. If successful, xdr-var-array returns the translated Scheme vector; otherwise, it returns #f. When decoding (i.e., translating from XDR representation), the resulting vector has the same length as the XDR array to be decoded. This example shows how to translate a variable-length, at most 10-element long, Scheme vector of integers (exacts) to its XDR representation as a variable-length array of shorts. See also other examples in this section. (define xdrobj (xdrmem-create '(0 . 2048) XDR_ENCODE)) (define (new-short) 0) (define vec (vector 1 2 3 4 5 6 7)) (xdr-var-array xdrobj vec xdr-short new-short 10) The XDR-to-Scheme translator described in this section is written by Aleksandar Bakić, using a parser generator due to Dominique Boucherd and a lexer generator due to Danny Dube. xdr-lex Lexes an XDR specification file. (xdr-lex xdr-filename) xdr-filename The name of the XDR file to be lexed. xdr-lex reads from file xdr-filename and outputs pairs (tokens) of the form (token-class . token-value), where token-class is an integer determining the class of a token (defined in module (pgrt xdr)) and token-value is the value associate with the token (#f if the token has no value). For the outputting, function display is used. This function is supposed to be used for checking purposes. (xdr-lex "sample.x") xdr-parse Parses and XDR specification file. (xdr-parse xdr-filename) xdr-filename The name of the XDR file to be parsed. xdr-parse reads from file xdr-filename, parses the contents, and stores the parse tree into variable xdr:specification, which is defined in module (pgrt xdr). This function is supposed to be used for checking purposes. (xdr-parse "sample.x") pretty-print-xdr-specification Pretty-prints an XDR specification, as a parse tree, to a file. (pretty-print-xdr-specification filename) filename The name of the file to which the contents of the xdr:specification variable (defined in module (pgrt xdr)) is written. pretty-print-xdr-specification writes the content of xdr:specification, using Scheme external representation and a pretty-printer, to file filename. This function is supposed to be used for checking purposes. Given that the contents of sample.x is const MY_LENGTH = 10; const HIS_LENGTH = 5; struct my_struct { long delta_time; short delta_voltage[MY_LENGTH]; struct his_struct currents; }; struct his_struct { long delta_time; short delta_current[HIS_LENGTH]; unsigned int dummy<>; }; calls to (xdr-parse "sample.x") (pretty-print-xdr-specification "sample.pp") will write the following to sample.pp ((xdr:constant-def ("MY_LENGTH" "10")) (xdr:constant-def ("HIS_LENGTH" "5")) (xdr:type-def (xdr:struct ("my_struct" ((xdr:simple-type-specifier (xdr:long) "delta_time") (xdr:fix-array-type-specifier (xdr:short) "delta_voltage" "MY_LENGTH") (xdr:simple-type-specifier (xdr:struct-type-spec "his_struct") "currents"))))) (xdr:type-def (xdr:struct ("his_struct" ((xdr:simple-type-specifier (xdr:long) "delta_time") (xdr:fix-array-type-specifier (xdr:short) "delta_current" "HIS_LENGTH") (xdr:var-array-type-specifier (xdr:u-int) "dummy" "XDR_MAX_LENGTH")))))) xdr-preprocess Preprocesses an XDR specification file. (xdr-preprocess xdr-filename) xdr-filename The name of the XDR file to be preprocessed. Often an XDR file contains cpp (a C/C++ preprocessor) #defines. xdr-preprocess tries to convert cpp #defines to Scheme defines. The resulting definitions are output using Scheme function display. In cases when #define is used to define a macro, xdr-preprocess replaces the macro by #t, and the user has to replace the #t manually. (xdr-preprocess "sample.x") xdr->scheme Translates an XDR specification file to a file containing corresponding Scheme code and data. (xdr->scheme xdr-basename) xdr-basename The basename of the XDR file to be translated to Scheme. xdr->scheme reads from file whose name is obtained by adding ".x" to xdr-basename, preprocesses, lexes, and parses its contents, and creates a file whose name is obtained by adding "_xdr.scm" to xdr-basename. The resulting file contains code and data needed to translate XDR data structures defined in the XDR file from their XDR representation to Scheme records (defined in SLIB struct module), and vice versa. None. The following call (xdr->scheme "sample") will read XDR sample.x and translate to Scheme file sample_xdr.scm. If the content of sample.x is the same as in the example for pretty-print-xdr-specification, the content of sample_xdr.scm is (use-modules (ice-9 slib) (pgrt xdr)) (require 'struct) (define MY_LENGTH 10) (define HIS_LENGTH 5) (define my_struct (make-record-type 'my_struct '(f1 f2 f3))) (define my_struct? (record-predicate my_struct)) (define new-my_struct (lambda () ((record-constructor my_struct '(f1 f2 f3)) (new-long) (make-vector MY_LENGTH (new-short)) (new-his_struct)))) (define my_struct.delta_time-ref (record-accessor my_struct 'f1)) (define my_struct.delta_time-set! (lambda (r v) (if (and (my_struct? r) (long? v)) ((record-modifier my_struct 'f1) r v) (throw 'xdr-error "Invalid record set!")))) (define my_struct.delta_voltage-ref (record-accessor my_struct 'f2)) (define my_struct.delta_voltage-set! (lambda (r v) (if (and (my_struct? r) (fix-vec? short? MY_LENGTH v)) ((record-modifier my_struct 'f2) r v) (throw 'xdr-error "Invalid record set!")))) (define my_struct.currents-ref (record-accessor my_struct 'f3)) (define my_struct.currents-set! (lambda (r v) (if (and (my_struct? r) (his_struct? v)) ((record-modifier my_struct 'f3) r v) (throw 'xdr-error "Invalid record set!")))) (define xdr-my_struct (lambda (xdr r) (let ((tr (new-my_struct))) (and (my_struct? r) (let ((tmp (xdr-long xdr (my_struct.delta_time-ref r)))) (if tmp (my_struct.delta_time-set! tr tmp) #f)) (let ((tmp (xdr-fix-array xdr (my_struct.delta_voltage-ref r) xdr-short new-short MY_LENGTH))) (if tmp (my_struct.delta_voltage-set! tr tmp) #f)) (let ((tmp (xdr-his_struct xdr (my_struct.currents-ref r)))) (if tmp (my_struct.currents-set! tr tmp) #f)) tr)))) (define his_struct (make-record-type 'his_struct '(f1 f2 f3))) (define his_struct? (record-predicate his_struct)) (define new-his_struct (lambda () ((record-constructor his_struct '(f1 f2 f3)) (new-long) (make-vector HIS_LENGTH (new-short)) (make-vector 0 (new-u_int))))) (define his_struct.delta_time-ref (record-accessor his_struct 'f1)) (define his_struct.delta_time-set! (lambda (r v) (if (and (his_struct? r) (long? v)) ((record-modifier his_struct 'f1) r v) (throw 'xdr-error "Invalid record set!")))) (define his_struct.delta_current-ref (record-accessor his_struct 'f2)) (define his_struct.delta_current-set! (lambda (r v) (if (and (his_struct? r) (fix-vec? short? HIS_LENGTH v)) ((record-modifier his_struct 'f2) r v) (throw 'xdr-error "Invalid record set!")))) (define his_struct.dummy-ref (record-accessor his_struct 'f3)) (define his_struct.dummy-set! (lambda (r v) (if (and (his_struct? r) (var-vec? u_int? XDR_MAX_LENGTH v)) ((record-modifier his_struct 'f3) r v) (throw 'xdr-error "Invalid record set!")))) (define xdr-his_struct (lambda (xdr r) (let ((tr (new-his_struct))) (and (his_struct? r) (let ((tmp (xdr-long xdr (his_struct.delta_time-ref r)))) (if tmp (his_struct.delta_time-set! tr tmp) #f)) (let ((tmp (xdr-fix-array xdr (his_struct.delta_current-ref r) xdr-short new-short HIS_LENGTH))) (if tmp (his_struct.delta_current-set! tr tmp) #f)) (let ((tmp (xdr-var-array xdr (his_struct.dummy-ref r) xdr-u_int new-u_int XDR_MAX_LENGTH))) (if tmp (his_struct.dummy-set! tr tmp) #f)) tr)))) ;;; eof XDR_ENCODE Has the value equal to the XDR library constant with the same name. XDR_DECODE Has the value equal to the XDR library constant with the same name. XDR_FREE Has the value equal to the XDR library constant with the same name. XDR_MAX_LENGTH Has the value of integer 4294967295, and is used for specifying the maximum length of XDR data (i.e., specifying that there is no practical limit). MAXSHORT Has the value equal to the C constant, defined in C header file values.h, with the same name. MAXINT Has the value equal to the C constant, defined in C header file values.h, with the same name. MAXFLOAT Has the value equal to the C constant, defined in C header file values.h, with the same name. The following data constructor and type checking functions are defined in module (pgrt xdr) that are used by files created by xdr->scheme: new-int, int?, new-enum, enum?, new-u_ing, u_int?, new-hyper, hyper?, new-u_hyper, u_hyper?, new-short, short?, new-u_short, u_short?, new-long, long?, new-u_long, u_long?, new-char (char? is the same as the &R4RS; primitive), new-u_char, u_char?, new-float, float?, new-double, double?, new-quadruple, quadruple?, new-bool, bool?, new-void, void?, fix-vec?, var-vec?, fix-string?, var-string?. For information of these functions' implementations, please refer to the file that implements module (pgrt xdr). To be added later.