Utilities Docs  This file includes Documentation for all files in the Utilities Drawer. They have all been combined into one to save disk space. The Docs included in this file are:  Dirk Jask TaskControl Clock & Config  Doc File Headers are in RED! *****************************************************************************  9/88 DIRK v0.01 -- Tune workbench colors to system performance  ----------------- Copyright (C) 1988 by Daniel Elbaum This software is freely redistributable provided that: the three files which comprise it (dirk, dirk.c, dirk.doc) remain intact; all copyright notices contained in any of the aforementioned files remain intact; and no fee beyond reasonable remuneration for collation and distribution be charged for use and/or purveyance. ----------------- Syntax: run dirk [-t|m] [-gN] [-bN] [-hN] [-lN] [-iN]] [+rN] [+gN] [+bN] Parameters: Option Default Effect --------------------------------------------------------------------- - t track tasks only m track memory only g 4 granularity of task mapping (small for few tasks) b 14 background saturation h 12 maximum detail saturation l 8 minimum detail saturation i 180 interval in ticks (60 or 50 per second) + r 8 base value for red component of detail pen g 8 base value for green component of detail pen b 8 base value for blue component of detail pen If you like the program, you may eventually want to start it from your startup-sequence, so you might want to dirk around with the options before deciding on a command line to use. Here they are. The -t option enables task tracking only. The background color is not affected. The -m option complements the -t option; only memory tracking is turned on. The detail pen color is not affected. The following command line options require counts. The valid range of the count varies from option to option. All color counts should be between 0 and 15; other counts must be between 0 and 65535. Granularity, set with -gN, is the sensitivity with which detail pen color responds to the instantaneous number of ready tasks. Workable values lie between 1 and 8. The background saturation argument, -bN, determines the brightness of the screen, which remains constant as hue varies. N is best set between 4 and 14. Maximum detail saturation (-hN) is a limit on the brightness of the detail pen. A value of 8 to 14 (14 brighter) can keep detail from glaring. The valid range is 0-15. Minimum detail saturation, -lN (ell not one) is a floor on the brightness of the pen, to maintain good contrast to the background. For a light background, l should be at least 8. The interval (-iN) is the number of ticks to wait between data retrieval expeditions. A tick is 1/60th of a second in the US, and 1/50 in Europe. If N is given as 0, the research and reporting are done constantly, and system performance slows slightly but noticeably. 180 corresponds to ~3 seconds, and is probably a good functional maximum. The + arguments specify the detail pen's basic color. As the number of tasks increases, the pen becomes dimmer, and as the proportion of active tasks increases, the pen becomes yellower. -rN sets the red component (0-15), -gN sets the green, and -bN sets the blue. It's worth experimenting to find a combination which provides good contrast. It all sounds confusing but once you run the program and see what it does, the meaning of the command line options will hopefully fall into place. ----------------- Description: The purpose of this program is to present key system information to the user without cluttering up the display. The workbench background color changes from blue through purple to red as the amount of free memory decreases. The workbench detail color (the color of text and Workbench window borders) changes from bright white to gray as the number of system tasks increases. Further, the yellow content of this color is increased according to the number of active tasks. On a newly-booted vanilla system, borders are white and the background is close to the standard Workbench blue. As you use the system, calling up programs and creating files on the RAMdisk, the screen takes on an increasingly reddish hue. When memory is nearly full, the background is completely red. Similarly, as tasks are added, the borders dim slightly. In other words, after you set up dmouse, conman, snipit, or whatever to run in the background, the detail color fades, eventually to grey. If many background tasks are active rather than just waiting around for an interrupt or message, the grey will be tinted yellow. With dirk running in the background, you always have a rough idea of how much memory is available and how busy the system is, without hunting around for the window of your favorite resource-tracking gizmo. ----------------- Signature and self-promo: If you want to send me money for dirk, then by all means do so--many projects are in progress and I need financing. $5.00 is recommended. Make checks payable to: Daniel Elbaum Amaranth Software 4816 SE Bybee Blvd. Portland, Ore. 97206 Send comments, suggestions, and flames to: Daniel Elbaum Portland bbs: Amigaboard!, NAG UUCP: ...!tektronix!reed!elbaum ARPA: elbaum@reed.EDU *****************************************************************************  Copyright 1988 by I2(EYE) Systems. JASK.DOC - Version 1.0 JASK - Intuitive Ask Replacement --------------------------------  JASK is a replacement for the ASK command distributed in the Amiga 1.3 enhancer package. It will allow the user to click on a gadget to specify a positive or negative response rather than type it in at the keyboard. You can move the "requester" to the bottom of the screen or to the front or back of other screens if you don't want to answer it at the moment. JASK Parameters --------------- -r This parameter specifies the "requester" text. This is the question you want to ask. This is the only REQUIRED parameter. (40 character max.) EXAMPLE: "-rYour MOMMA is ?" = Your MOMMA is ? in the requester box. (put quotes around the string to put spaces in the text) -p This specifies the text for the positive (left) gadget. When this gadget is selected, WARN (5) will be returned. (put quotes around the string to put spaces in the text) DEFAULT: YES (12 character max.) EXAMPLE: -pUGLY = UGLY in the left gadget. -n This specifies the text for the negative (right) gadget. When this gadget is selected, 0 will be returned (success). (put quotes around the string to put spaces in the text) DEFAULT: NO (12 character max.) EXAMPLE: -nPHAT = PHAT in the right gadget. -t This will specify a timeout period in seconds. When the timeout period expires, the default answer will be returned. DEFAULT: wait forever EXAMPLE: -t10 = wait 10 seconds. -d This parameter specifies which gadget is the default (safe) answer. It does two things: a) determines if the positive or negative answer is to be default. b) makes a more extravagant border for the specified gadget. n specifies the negative answer, p specifies the positive answer. DEFAULT: if this is not specified, both gadgets will look the same, but the negative gadget will be returned. EXAMPLE: -dp = Fancy gadget rendered on positive and positive is the default answer. -q This specifies whether you want the "requester" quick or if you want the "requester" to scroll up. DEFAULT: the "requester" scrolls up to it final position. EXAMPLE: -q = turn off the scrolling effects. This software may be freely distributed provided that this notice is retained. It may be hacked or used as is in any product as long as you credit me for it. If you find this program useful for enhancing your script file capabilites or as example source code, please send $5.00 to: I2(EYE) Systems 6620 Hunter Road Elkridge, MD 21227 Attn: J. Barshinger Note: if you send $10.00, I'll send you the latest enhancements. Planned enhancements include a re-entrant version so that it can be made resident and a mouse-move capability that will automatically move the pointer to the default gadget. USENET or ARPANET: barsh@stsci *****************************************************************************  TaskControl / / / by J. Martin Hippele  TaskControl is a nicely done, graphically representative task-handling program which allows you to put to sleep, kill, or change priorities of all of your currently loaded tasks. This program is a potentially GURU-producing program, so be careful which tasks you kill, change priorities of, etc. Handy window sizer will reduce it almost to an icon to hang around until you want to use it. *****************************************************************************  CLOCK & CONFIG  PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY DEEMU USER MODIFIABLE EXECUTABLE EMBEDDED DATA Matthew Dillon (SNAIL) 891 Regal Rd. Berkeley, Ca. 94708 USA dillon@ucbvax.Berkeley.EDU (APRANET) ...!ihnp4!ucbvax!dillon (USENET) 30 July 1988 Includes: CONFIG -V1.00 of my config program CLOCK -V1.00 of my really-small non-intrusive clock program (which uses DEEMU for window placement) DEEMU.DOC -Docs on DEEMU SCRIPT.TXT -Example script of configuring the clock executable MAKEFILE CONFIG.C CLOCK.C This document describes DEEMU, which allows end users to modify various parameters of a program by directly modifying the executable in question through standard programs. This is what happens: (1) The programmer embedds a DEEMU structure at the very beginning of his initialized data hunk. Since the C startup module usually contains only BSS declarations, a simple C declaration at the beginning of your first module will suffice. ** THIS HAS BEEN TESTED WITH AZTEC C. COULD SOMEBODY PLEASE TEST IT WITH LATTICE? (2) The user comes along and can modify various DEEMU entries in the executable to customize the program to his needs. Thus, the programmer need not put any extra code into his program to allow the user to modify parameters from the program. Additionaly, the script or initialization files that would otherwise have been required are now nonexistant, making the user's enviroment that much more streamlined and clean. STRUCTURE FORMAT The programm should put the following declaration at the beginning of his first C (or assembly, or whatever) module: long Deemu[] = { 'STRT', 0, (other DEEMU entries) 'END ', 0 }; Note that the name of the array is arbitrary. This is an array of longwords consisting of a START entry, intermediate entries, and an END entry. The format of each entry is: long type; -longword describing the structure type uword flags; -RESERVED, SET TO 0 uword bytes; -# of bytes char data[bytes] + PAD0 -The structure data, padded to a WORD BOUNDRY The CONFIG program (yours, mine, anybody's) will check for 'STRT', 0 at the beginning of every DATA HUNK in the program until it finds one, then verifies the entire structure all the way to the 'END ', 0 is correct, then prompts the user with the various structures allowing him to modify them. The user gets very nice descriptive prompts for structure types that CONFIG knows about. The user can still modify structures CONFIG does not know about, but will not get the descriptive prompts. ALL STRUCTURES ARE WORD ALIGNED. That is, if a structure is not word aligned it should be padded with a 0 at the end to make it so. Thus, EVEN WHEN THE #BYTES IS NOT WORD SIZED, the #bytes is extended to a longword boundry to find the next DEEMU entry: bytes = (bytes+1)&~1 Fields within the structure need not be word aligned. This allows you to embed standard Amiga structures. STANDARD STRUCTURES Since this is the first release, only a couple custom structures have been defined so far. NOTE #1: The entire structure need not be entered. It is perfectly acceptable to cut out the tail ends of structures that you do not want to bother with. For instance, you might have the following for a NewWindow structure: 'NW ', 10, (short leftedge, topedge, width, height, ubyte detpen, blockpen) OR 'NW ', 9, (short leftedge, topedge, width, height, ubyte detpen) + one byte padding. In this case, the CONFIG program only prompts for those fields that exist. NOTE #2: Structures may be longer than the 'standard' size. For future compatibility. The DEEMU program will prompt for these fields but will not be able to give descriptions of them to the user. STRT { The START structure, must be the first DEEMU structure. long type = 'STRT'; word flags= 0; word size = 0; }; END { The END structure, must be the last DEEMU structure. long type = 'END '; word flags= 0; word size = 0; }; TEXT { long type = 'TEXT'; word flags= 0; word size = N char prompt[A]; N = A + B. This includes the \0 after each string char contents[B]; }; The contents string need not be exactly B long, but may terminate with a \0 before it reaches the maximum allowed length. In this case the extra bytes at the end may be garbage. The contents string is thus limited to N-strlen(A)-2 character bytes, not including the \0. THE PROMPT STRING MAY NOT BE MODIFIED BY THE USER. SEE CLOCK.C FOR EXAMPLE USAGE OF 'TEXT'. NOP { long type = 'NOP '; word flags = 0; word size = N; }; No operation. The data, if any, can be modified, but will probably not be used by the program. DATA { long type = 'DATA'; word flags = 0; word size = N; }; Program dependant data. Contents and ordering are defined by the program. The documentation for the program will tell you which word means what (the CONFIG program prompts for the data in WORD sized chunks). TRCT { long type = 'TRCT'; word flags = 0; word size = N; short pri; short cpu; long chipmem; long generalmem; }; Task/Resource Control. Dynamic specification of the task priority. pri: Specify the task priority. If bit 8 ($100) is set, an absolute priority is given in the low byte. If bit 8 is clear, a priority relative to the startup-priority is given. (i.e. a 1 means, 1 over my priority when I started up). cpu: 0-FFFF Specify how much of a CPU hog this program can be, in percentage (FFFF=100%). Most programs ignore the field. chipmem/generalmem: some value representing the maximum #bytes of memory you want this program to use. These fields do not apply to most programs but could come in useful in, say, a disk cache program or something like that. NOTE that there is no specification for 'fast' memory. chipmem refers to specific CHIP allocations the program makes, and generalmem refers to non-specific allocations the program might make. NW { long type = 'NW '; word flags= 0; word size = N; (usually 8 or 10 bytes.. partial NewWindow structure) (A partial NewWindow structure) }; struct NewWindow NW; 'NW ', (0-sizeof(NewWindow))L, The NewWindow structure. However, the contents of LeftEdge, TopEdge, Width, and Height, are allowed to be NEGATIVE. TopEdge < 0 : specify right edge relative to screen right LeftEdge < 0 : specify bottom edge relative to screen bottom Width <= 0 : specify width relative to screen Width Height <= 0 : specify height relative to screen height The programmer should do a sanity check of parameters after adjusting them properly. The GetScreenData() should be used to retrieve screen information. For instance, specifying -1, -1 places the window as follows: ActualLeftEdge = Screen.Width - Nw.Width - 1; ActualTopEdge = Screen.Height- Nw.Height- 1; SPECIFYING 0 FOR THE Nw.Width and/or Nw.Height should cause the window to be openned to its fullest size in that dimension. IF YOU USE THE 'NW ' DEEMU STRUCTURE, YOU MUST BE ABLE TO HANDLE THESE SPECIAL CONDITION! EXAMPLE short Deemu[] = { 'ST','RT', 0, 0, 'NW',' ', 0, 9, -16, -8, 64, 32, -1, 0, 'TE','XT', 0, 16, 'HI', '\0T', 'ES', 'T.', 0, 0, 0, 0, 'EN','ND', 0, 0 }; We have a STRT structure of 0 length (it MUST be 0 length). We then have the first 9 bytes of a NewWindow structure: short LeftEdge = -16; short TopEdge = -8; short Width = 64; short Height = 32; char DetailPen= -1; NOTE: The NW structure is padded to a word boundry with a 0, this 0 is *NOT*, I repeat *NOT* the char BlockPen; specification, which normally comes after DetailPen. And, before the END we have a 'TEXT' entry with the prompt "HI" and the contents "TEST". The user is allowed to modify the contents and up to 12 characters (not including the \0) may be used. For TEXT, no more than 128 bytes total should be allocated. LIMITATIONS Currently the config program only checks the first 32 longwords of each DATA hunk. This is done mainly to prevent the possibility that non DEEMU data might look like a DEEMU header, but also taking into account that the linker might put some amount of data in the hunk before it gets to the DEEMU data. The Aztec linker (don't know about the others) sticks stuff before your own (jump tables when using the small code model). If your program is big enough, the DEEMU data might be out of reach. The solution is to place the DEEMU data in its own hunk, which can be accomplished with a little more work and various linker options. Future CONFIG programs will fix the problem. Example session with Config, configuring CLOCK. Please refer to CLOCK.C to see how the DEEMU structure is embedded and how the clock program handles the data. This particular script file shows placing the analog clock as a 32x16 window in the upper right hand corner of the screen. -Matt 1> config clock CONFIG V1.00, Matthew Dillon 2 entries found ----(NW , 8): NEW WINDOW STRUCTURE note: (Negative = Relative to Screen Right) LeftEdge ( $0000 0) : -1 note: (Negative = Relative to Screen Bottom) TopEdge ( $0000 0) : 10 note: (0 = Full Width, < 0 = ScreenWidth - (-width) Width ( $0020 32) : note: (0 = Full Height,< 0 = ScreenHeight- (-height) Height ( $0010 16) : ----(TEXT,16): TEXT HI (12 chars max) ( TEST.) : IWasHere Write data back to file (y/n): y File updated 1> *****************************************************************************