VIRUS The VIRUS program allows the experienced user to access and/or modify the data found in CUSP database files of various types. The first-time user of VIRUS should practice on test copies of files in order to familiarize themselves with VIRUS operations BEFORE he/she attempts to modify network archival data. VIRUS command headings are listed below in uppercase, use lowercase commands in response to the program prompt. EXIT Syntax: exit Exits the program immediately (stop and quit are equivalents). MEMORY VECTOR/TUPLE INITIALIZATION COMMANDS INIT Syntax: init Same as KINIT command KINIT Syntax: kinit Initializes the front-end of the memory vector array using data attributes definitions found in the file defined by the environmental variable: DDL_, a where "type" is data structure such as: event or setup. With the exception of the EVT command (which does a KINIT), KINIT should always be the first VIRUS command issued. If .mem files are to be accessed, this command should be followed by a MATCH command. This command only needs to be executed ONCE for a given data structure type. Example: vir>kinit setup MATCH Syntax: match Establishes an event memory vector data region in the format used for .mem type files. Assumes a single key type = 0. MATCH command is issued following either the KINIT EVENT or KINIT SETUP commands. The EVT command automatically performs the MATCH operation. After this command is issued the data can be loaded using MEMLOD for SETUP.MEM files or MEMGET for an event file. Database tuple access is acheived by using the "M"-type commands: MGET, MGETEQ, MGETGT, MNEXT, MPUT and MDROP. NULL Syntax: null Initializes the tuple/record key in the current/scratch tuple region of the event memory array. Overwrites existing values with null values. Used prior to storing new relational key attributes (see PUTAT) and after the memory vector attribute definition region has been initialized by KINIT. Nulling is automatically performed by the commands: EVT, PIN, SET, and SUM. Example: vir>null PUTAT Syntax: putat Enters the specified value for the specified attribute into the current memory tuple/search vector. Valid attribute names and their data types are defined in the .ddl file used to initialize the memory array (see KINIT command.) PUTAT is used to define the index key elements of the current tuple probe in the memory vector as well as non-key attributes. Note: all attributes are uppercase. Example: vir>putat RID SET vir>putat SET 1 vir>putat PIN 10 GETAT Syntax: getat Lists the value of the named attribute. Valid attribute names and their data types are defined in the .ddl file used to initialize memory (see KINIT command.) The specified attribute must have been loaded into the current memory tuple by a previous PUTAT or MGET type command. Note: all attributes are uppercase. Example: vir>getat RID SET vir>getat SET 1 vir>getat PIN 109 .MEM FILE I/O COMMANDS MEMGET Syntax: memget Loads the memory vector data region with the contents of the event file: x.mem This command must be preceded by the KINIT and MATCH commands. MEMPUT Syntax: memput [cusp-id] , (if id is absent, last id input is used) Writes the contents of the memory vector data region [K(K(1)+ 2) ...] into the disk file x.mem. The memory vector data region must have been previously loaded by MEMGET, MEMLOD, or either MEMBLD or MEMNEW followed by multiple MPUT commands. Issue this command if you want to update the event disk file with all modifications that were made to the memory vector data region. MEMLOD Syntax: memlod Loads the memory-vector data region [K(K(1)+ 2) ...] with the contents of the disk file .mem. This command must be used to load data from a setup.mem file; it can also be used load data from event x.mem files. If the filename suffix .mem is absent, it is appended to the filename. This command must be preceded by the KINIT and MATCH commands. Example vir>memlod setup.mem MEMDMP Syntax: memdmp Writes the contents of the memory-vector data region [K(K(1)+ 2) ...] into the disk file .MEM. This command must be used to write data to a setup.mem file; it can also be used to dump the memory data array to an event x.mem file. If the filename suffix .mem is absent, it is appended to the filename. Issue this command if you want to update the disk file with all modifications that were made to the database in the memory vector. Example: vir>memdmp setup.mem EVT Syntax: evt A quick way of setting up for probing an event .mem file. Equivalent to the the command sequence: kinit event match memget null This command only needs to be issued once; to read another event file into memory use then MEMGET or MEMLOD commands followed by NULL. Refer to cusp/Data/event.doc whenever you need to know the structure of specific tuples within the event database. .MEM DATABASE MEMORY TUPLE TRANSFER COMMANDS MPUT Syntax: mput Transfers the contents of current tuple/search vector to the data region of the memory vector (the data region is what is written out to disk as a .mem file by the MEMPUT and MEMDMP commands). MGET Syntax: mget Searches the data region of the event memory vector for a tuple with an index key either matching or greater than that of the index of the current memory tuple/probe; the current tuple's key attributes must have had values assigned by previous PUTAT or previous MNEXT or MGET-type commands. If found, the contents of the data area tuple are transfered into the current probe tuple (scratch storage). MGETGT Syntax: mgetgt Searches the data region of the event memory vector for a tuple with an index key greater than that of the index of the current memory tuple/probe; the current tuple's key attributes must have had values assigned by previous PUTAT or by previous MNEXT or MGET-type commands. If found, the contents of the data area tuple are transfered into the current probe tuple (scratch storage). MGETEQ Syntax: mgeteq Searches the data region of the event memory vector for a tuple with an index key matching that of the index of the current memory tuple/probe; the current tuple's key attributes must have had values assigned by previous PUTAT or by previous MNEXT or MGET-type commands. If found, the contents of the data area tuple are transfered into the current probe tuple (scratch storage). MNEXT Syntax: mnext Recovers from the data region of the event memory vector the next sequential tuple. If found, the contents of the data area tuple are written into the current probe tuple (scratch storage). MDROP Syntax: mdrop Deletes from the memory vector data region the tuple whose index matches that of the current tuple/probe; the current tuple must have been filled by an MNEXT or MGET-type command for DROP to work. DT Syntax: dt Lists the integer and octal equivalents of each byte in the current memory tuple also lists each attribute and its value to the terminal and to a file named "virus.dmp". MDUMP Syntax: mdump Lists the integer equivalents of each byte in the data region of the memory vector (the region occupied by the contents of a .mem file.) This amounts to 100's of lines, is of questionable value, and is not recommended. PIN Syntax: pin Searches an event vector data region for a pin-tuple of the type specified by the relational id (rid), whose set attribute value matches that specified and whose pin attribute is identical to or greater than that specified. If such a tuple is found, the contents of the data tuple are transferred into the current memory tuple; if not found, the current memory tuple remains unchanged. See cusp/Data/event.doc for a listing of pin tuple rids. Example: vir>pin PIN 1 109 SET Syntax: set Searches an event vector data region for a set-tuple of the type specified by the relational id (rid) and whose set attribute value matches that specified. If such a tuple is found, the contents of the tuple are trans- ferred into the current memory/probe tuple; if not found, the current memory tuple remains unchanged. See cusp/Data/event.doc for a listing of set tuple rids. Example: vir>set SET 1 SUM Syntax: sum Searches an event vector data region for a summary-tuple of type specified by the relational id (rid). If such a tuple is found, the contents of the tuple are transferred into the current memory/probe tuple; if not found, the current memory tuple remains unchanged. See cusp/Data/event.doc for a listing of possible summary tuple rids. Example: vir>sum ARK MEMNEW Syntax: memnew Creates in the memory vector a new event data region, assigns the event the next available cusp id (EVENT.SEQ). This command must be preceded by the KINIT and MATCH commands. The MEMNEW command would only be used if you wanted to build an event .mem file from scratch/probe entries. (The MEMBLD command is identical except that the id assigned to the event is the id specified on the command line.) MEMBLD Syntax: membld Creates in the memory vector a new event data region, assigns the event the specified cusp id. This command must be preceded by the KINIT and MATCH commands. The MEMBLD command would only be used if you wanted to build an event .mem file from scratch/probe entries. (The MEMNEW command is similar except that the id assigned to the event is the next available cusp id from EVENT.SEQ.) KILL Syntax: kill Deletes from an event memory vector data region any tuple whose relational id key attribute (rid) matches that specified. The rid is a 1-3 character string which identifies the tuple type (e.g. HYP, ARK, PIX). Example: vir>kill PIX GETID Syntax: getid Returns the event .mem file and .grm file ids stored in the memory vector data region. These ids are also referred to as the child and parent or the clone and parent ids. The parent id is always the numeric id of the .grm file. PUTID Syntax: putid Changes the event .mem file and .grm file ids stored in the memory vector data region. These ids are also referred to as the child and parent or the clone and parent ids. The parent id is always the numeric id of the .grm file. The only reason why this command would ever be used is if some user written CUSP program which accessed these two ids through the BV subroutines in dbms routines made an error in the id assignments. Do not use this command unless the network manager okays it. TUPLE/RECORD STRUCTURES Summary of setup.mem tuples (see cusp/Base/setup.ddl) KEY = 0 RID SITE NET PHASE Data attributes (* = null) RID = "TIT" : < * >< * >< * >| RID = "MOD" : < * >< * >| RID = "NET" : < * >| RID = "ORG" : < * >< * >< * >| RID = "DLY" : | RID = "POS" : < * >< * >< * >| RID = "TRY" : < * >< * >| RID = "MAG" : < * >|