CTOS COLOR UTILITIES Release Level 12.1.11B This application consists of the following files: ColorConfigure.Run ColorService.Run ColorSetup.Run InstallColorService.Run CmColor.Run ColorConfig.Sys KribaboColorConfig.Sys KribaboSoftMsg.Bin KribaboSoftMsg.Txt Product Name : CTOS Color Utilities Supported On : B24, B26, B27, B28, B38, B39, and all SuperGen hardware Supported OS : BTOS II, CTOS I, CTOS II, CTOS III Description : The CTOS COLOR UTILITIES have been designed to implement the use of color in a consistent way. They allow the user to configure, setup, change and maintain colors. The COLOR UTILITIES also include an API thru which applications can implement colors in the same way. The API is available thru the 12.1.11 (or higher) CTOSKrivabo.Lib package. The COLOR UTILITIES mainly are targetted to non-graphical applications but this does not mean that graphical applications are excluded. The COLOR UTILITIES implement color thru the Three- Palette Format and for graphical applications the One-Palette Format may be more suitable. The CTOS COLOR UTILITIES support the following features: - all utilities + the API make use of a color configuration file that can hold up to 20 color palettes. Each color palette consists of 8 foreground and twice 8 background or graphics colors. - There is a choice of 64 different colors. Every user can easily adjust the colors to his own preference. - Colors also can be set up for applications that have been designed for monochrome workstations. These applications will use one color for the normal video attribute and another for the half-bright video attribute. A background color can be defined if the color monitor supports background color and Config.sys contains the ':EVBackgroundOff:NO' entry. - Per partition 8 foreground colors and 1 background color are maintained for applications that use colors but do not set them up. This means that when application A, which has redefined the colors being used, exits to the EXECUTIVE the colors will be restored automatically to the colors that were being used before application A was invoked. - Thru the use of ACTION keys, the colors being displayed by an application may be changed interactively without stopping the application. This feature makes it possible to have color when running OFIS DOCUMENT DESIGNER in WYSIWYG mode and as such reduces eye fatigue. - Color can be set up when invoking an application thru Context Manager. - XE530 applications run thru CLUSTER VIEW may also run in color mode. However, as CTOS/XE actually does not support color, this feature can not be guaranteed for 100% but so far problems have not been encountered. Directions/Use : The COLOR CONFIGURE utility is used to create and modify a color configuration file which can hold up to 20 color palettes. Each color palette consists of three 8-byte arrays (or palettes): - Foreground palette - Background1 palette - Background2 palette NOTE: Whenever you read 'color palette' in this text, it refers to a structure containing the above three 8-byte palettes. The Foreground Palette is an array of 8 alphanumeric character colors. The other two palettes 'Background1' and 'Background2' are arrays of 8 background colors. However, they also may be used to define graphics colors. When defining background colors each of the 8 entries in a background palette corresponds to the same entry in the foreground palette. This means that for each of the 8 foreground colors, you may define a different background color. Note, however, that to enhance screen readability, in most cases you will want to give all entries in a background palette the same value. The Color Utilities include a default ColorConfig.sys file. This color configuration file contains 20 color palettes. For each of them the Background1 palette defines a background color that matches the corresponding Foreground palette. The Background2 palettes have been configured for use with the COLOR SERVICE and OFIS DOCUMENT DESIGNER in WYSIWYG mode. The first entry in the Background2 palette defines the background color and the second entry the foreground color. COLOR CONFIGURE The following instructions explain the use of the Color Config utility: In the right hand corner of the screen you find the name of the color configuration file. A few lines down you see the number of the color palette that is being shown. It is followed by the string 'Foreground/Background1/Background2' whose Bold and Underline attributes tell you which palette within the color palette you currently have selected. A few lines down you see 8 colored squares which are numbered from left to Right (C0, C1, ..., C7). These 8 squares represent the 8 colors in the foreground palette. Each of these squares is surrounded by another colored square which represents the corresponding background color (background1 or background2). Finally, a border is drawn around one of the background color squares. It tells you which of the entries you have selected. Note: On color monitors that do not support background color, foreground and background color can not be shown together. So when you select a background palette, it is shown in the same way as the foreground palette (i.e. using the inner squares). This allows you to create a color configuration file with background colors on a workstation that does not support background colors. The disadvantage is that the screen may be hard to read when configuring these background colors. Below each of the colored squares the corresponding color value for the selected palette is shown. The color value is a number between 0 and 63 (there is a choice of 64 colors). For the selected color entry also the red, green and blue intensity levels are shown. The intensity levels have a value between 0 and 3 where 3 means full intensity. Finally, at the bottom of the screen help is being shown for every supported keystroke. Each time you press the HELP key, the next section of help is displayed. Pressing SHIFT-SCROLL UP or SHIFT-SCROLL DOWN scrolls you thru the help one message at a time. When running Color Configure you can select from the keystroke functions described below: Keystroke Function --------- -------------------------------------------- CODE-COPY Copies and inserts the selected color palette before the current one. The number of color palettes is increased by one. To use, first select a color palette, scroll to the palette before which you want to add a color palette and press CODE-COPY. CODE-S Saves all changes to the color configuration file. CODE-U Discards all changes made since the last save. COPY Overwrites the current color palette with the selected one. To use, first select a color palette, scroll to the color palette you want to change and press COPY to overwrite it with the selected color palette. DELETE Deletes a color palette. DOWN ARROW Decreases the color value or color level of the selected color entry. When zero has been reached, the color value changes to 63 and the color level to 3. F9 Sets all background colors within the selected background palette to background color0 of that background palette. For example, to set all entries of the background1 palette to 18, select color entry 0 of the background1 palette, change the color value to 18 and press function key F9 to change color entries 1 - 7 to color value 18. F10 Cycles thru Foreground/Background1/Background2. Each time you press function key F10, the next palette within a color palette is selected. FINISH Finishes a Color Configure session. You are asked whether you want to save your changes or not. HELP Cycles thru the help messages. Each time you press HELP the next section of help is displayed. LEFT ARROW Cycles from right to left (7 to 0) thru the 8 color entries within a palette. It is used to select a color entry. MARK Selects a color palette for copying or moving. A selected palette remains selected until you press MOVE or CODE-U. MOVE Moves and inserts the selected color palette before the current one. As a result the selected color palette gets a different color palette number. The total number of color palettes remains the same. To use, first select a color palette and scroll to the color palette before which you want to insert the selected color palette, then press MOVE. RETURN A color entry can be changed by modifying its color value or it's red, green or blue level. With the RETURN or TAB keys you can choose which of these four values you want to change. The selection is shown in reverse video. RIGHT ARROW Cycles from left to right (0 to 7) thru the 8 color entries within a palette. It is used to select a color entry. SCROLL DOWN Cycles thru the color palettes in ascending order. After reaching the last color palette, you go back to color palette 0. SCROLL UP Cycles thru the color palettes in descending order. After reaching the first color palette, you go back to last color palette. SHIFT-COPY Overwrites the current foreground or background palette with the selected one. To use, first select a color palette, scroll to the color palette you want to change, select a foreground or background palette and press COPY to overwrite it with the corresponding palette of the selected color palette. SHIFT-SCROLL DOWN Scrolls thru the help messages. SHIFT-SCROLL UP Scrolls thru the help messages. TAB A color entry can be changed by modifying its color value or it's red, green or blue level. With the RETURN or TAB keys you can choose which of these four values you want to change. The selection is shown in reverse video. UP ARROW Increases the color value or color level of the selected color entry. When the maximum value has been reached, the color value and the color level change to 0. For the COPY, DELETE, DISCARD, FINISH and MOVE functions, the user is always prompted to confirm or cancel the operation. The prompts are detailed enough to avoid mistakes. For example, for the MOVE function the prompt looks like: "Press GO to move color palette 0 and insert it before color palette 5, CANCEL to cancel command" When creating a new color configuration file, there initially is one color palette which inherits the colors of the color palette in use before invoking /COLOR CONFIGURE. When running COLOR CONFIGURE on an XE530 thru CLUSTER VIEW, COLOR CONFIGURE searches your .user file for the following entries: :ClusterViewColor:Yes :ClusterViewBackgroundColor:Yes If these entries are 'Yes', COLOR CONFIGURE assumes that the workstation supports color and background color and /COLOR CONFIGURE can be executed as on a workstation. To execute the Color Configure utility, run the /Color Configure command with the following parameter which is outlined and detailed below: [Color config file] This field is optional. The default is [Sys]ColorConfig.sys. Enter the name of the color configuration file to be created or modified. COLOR SETUP The COLOR SETUP utility retrieves a specified color palette from a color configuration file and changes the default screen colors accordingly. COLOR SETUP can also be run on the XE530 thru CLUSTER VIEW if you change your .user file as explained above. The Color Setup utility may be run by executing the /Color Setup command using the following parameters which are detailed and explained below: [Color palette number] This field is optional. The default is color palette 0. Enter the number of the color palette to be used. [Color config file] This field is optional. The default is [sys]ColorConfig.sys. Enter the name of the color configuration file to be used. CMCOLOR UTILITY CmColor.run gives you the same functionality as the COLOR SETUP command but it is used when invoking an application thru CONTEXT MANAGER. The CmColor utility uses the following tokens within your Context Manager config file: :CmColorPalette: The default is color palette 0. Specify the number of the color palette to be used. :CmColorConfigFile: The default is [sys]ColorConfig.sys. Specify the name of the color configuration file to be used. :CmRunFileName: There is no default. Specify the name of the run file to be invoked. The following are examples of CM config file entries which demonstrate the CmColor utility: :CommandName:Executive --> :RunFileName:[sys]CmColor.run :CommandAbbreviation: Exec :MemorySize:<800 :CommandCase:00 :FunctionKey:1 :Autostart:1 :Invoker:n :Volume: :Directory: :Prefix: :Password: :Node: :Color:green :Resolution:1024x768 --> :CmColorConfigFile:[sys]ColorConfig.sys --> :CmColorPalette:0 --> :CmRunFileName:[sys]Exec.run :CommandName:UTS --> :RunFileName:[sys]CmColor.run :CommandAbbreviation: UTS :MemorySize:250 :CommandCase:0 :FunctionKey:4 :Autostart:0 :Invoker:Y :Volume:Sys :Directory:Work :Prefix: :Password: :Node: :Color:green :Resolution:720x348 --> :CmColorConfigFile:[sys]ColorConfig.sys --> :CmColorPalette:4 --> :CmRunFileName:[sys]UTE.run :Params:3/ COLOR SERVICE The COLOR SERVICE service serves two functions. The first function allows the user to interactively change the current foreground and/or background colors of any foreground application. The second function (color correction filter), which is optional, maintains the eight foreground and one background colors defined in an application partition's ASCB structure when CLUSTER VIEW, the EXECUTIVE or SIGNON get reloaded. Additionally, the color correction filter makes it also possible to run WYSIWYG OFIS DOCUMENT DESIGNER in color mode when CONTEXT MANAGER is not installed. When you install the color service, all the color palettes in the specified color configuration file are stored in memory. Subsequently, thru ACTION key commands the colors of any foreground application can be changed to the colors defined in any of these color palettes. For alphanumeric applications the background1 palette is used to set the background colors and for graphics applications the background2 palette is used to set the graphics colors. For example, when running OFIS DOCUMENT DESIGNER in WYSIWYG mode, entry 0 of the background2 palette defines the background color and entry 1 the foreground colors. OFIS DOCUMENT DESIGNER does not use the other entries. When you change the colors thru an ACTION key command, this change is only effective for the current application unless the EXECUTIVE is running. This means that if you change the colors while running PARTITION STATUS or OFIS DOCUMENT DESIGNER for example, and you exit to the EXECUTIVE then the colors will be restored to the colors the EXECUTIVE was using before running PARTITION STATUS or OFIS DOCUMENT DESIGNER (i.e. the colors stored in the ASCB structure). However, if you change the colors while running the EXECUTIVE, the new colors will be stored in the application partition's ASCB and as such they become the new default colors. The COLOR SERVICE supports the keystroke functions described below: Keystroke Function --------- ----------------------------------- ACTION-Enable_Action_Keys Enables the other supported ACTION keys for a (default = ACTION-e) period of 5 seconds. Unless you press this ACTION key first, the other ACTION keys will be ignored. When pressing a valid ACTION key during this period, the 5 seconds start running again. During the ACTION key enable period, the ACTION-Enable_Action_Keys key has a second function. It is used to toggle between single/double digit color palette numbers. ACTION-n Changes the colors of the foreground application to the colors defined in color palette n. Color palettes 10 to 19 may be selected by pressing ACTION- Enable_Action_Keys twice followed by ACTION-m and ACTION-n where 'mn' becomes the color palette number. m and n are the 0-9 keys on the alphanumeric key pad. As a default both the foreground and background colors are changed. You may, however, change this with the ACTION-Background_Color and ACTION-Foreground_Color ACTION keys. ACTION-Background_Color Tells the color service that all subsequent color (default = ACTION- r) changes during the current ACTION key enable period should only affect the background colors (i.e. when selecting another color palette, only the background colors will be changed. Pressing it a second time enables the foreground color changes again. So it is actually a toggle command. ACTION-Foreground_Color Tells the color service that all subsequent color (default = ACTION- f) changes during the current ACTION key enable period should only affect the foreground colors (i.e. when selecting another color palette, only the foreground colors will be changed. Pressing it a second time enables the background color changes again. So it is actually a toggle command. ACTION-ColorCycle Changes the colors of the foreground application to (default = ACTION-+) the colors defined in the next color palette. After reaching the last color palette, the next one is color palette 0. NOTE: The ACTION-Background_Color, ACTION-Foreground_Color and ACTION-ColorCycle ACTION keys may be disabled by specifying 255 as ACTION key value when installing the color service. When the 12.0.x, 12.1.x and 12.2.x EXECUTIVE, and the 12.0.x and 12.1.x SIGNON reinitialize the video, they reduce the 8 colors of the foreground palette to two colors. The first two ASCB.rgbColorBytes are copied to the other six. As a result we get 4 times the same two colors. This bug can be avoided by activating the optional Color Correction Filter which attempts to maintain the the colors defined in the ASCB structure. Furthermore, the Color Correction Filter maintains your colors when you invoke CLUSTER VIEW. The filter also should be activated if you want to use the COLOR SERVICE to switch on color when running WYSIWYG OFIS DOCUMENT DESIGNER when Context Manager is not installed. The Color Service may be installed by executing the /Install Color Service command using the parameters which are detailed and explained below: [Color config file] This field is optional. The default is [sys]ColorConfig.sys. Enter the name of the color configuration file to be used. [Enable ACTION-key (65h or 'e')] This field is optional. The default is 'e'. Enter the key to be used for enabling the other ACTION keys. You can either enter the key itself or its character code. For example, to specify the 'w' key you may enter 'w', '77h' or '119'. (*) [Foreground ACTION-key (66h or 'f')] This field is optional. The default is 'f'. Enter the key to be used as the ACTION-Foreground_Color key. You can either enter the key itself or its character code. For example, to specify the 'w' key you may enter 'w', '77h' or '119'. Enter 'FFh' or '255' to disable this function. [Background ACTION-key (72h or 'r')] This field is optional. The default is 'r'. Enter the key to be used as the ACTION-Background_Color key. You can either enter the key itself or its character code. For example, to specify the 'w' key you may enter 'w', '77h' or '119'. Enter 'FFh' or '255' to disable this function. [Color cycle ACTION-key (2Bh or '+')] This field is optional. The default is '+'. Enter the key to be used as the ACTION-ColorCycle key. You can either enter the key itself or its character code. For example, to specify the 'w' key you may enter 'w', '77h' or '119'. Enter 'FFh' or '255' to disable this function. [Activate color correction filter?] This field is optional. The default is No. Enter 'Yes' to activate the color correction filter. [Signon color palette number (0)] This field is optional. The default is color palette 0. Enter the number of a color palette. If the Color Correction Filter has been activated, this color palette will be used when Signon.run is running. If the Color Correction Filter is not active, this parameter is ignored. Enter 'FFh' or '255' if you do not want to overwrite the color palette set up by Signon.run (e.g. 12.2 Signon). [Maximum number of partitions (50)] This field is optional. The default is 50. Enter the maximum number of partitions that may be in use at any time. This parameter is used to calculate the amount of memory that should be allocated when activating the filter. NOTE: When running CTOS II 3.0 or higher, the utility will automatically convert the specified character code to the corresponding key post value of your local keyboard. Below CTOS II 3.0 this conversion does not occur and you actually may have to specify key post values instead of character codes. DEINSTALL COLOR SERVICE Deinstall Color Service will fail with erc 206 if programs that filter the ProgramColorMapper, ResetVideoGraphics and SetScreenVidAttrs requests have been invoked after installing the color service with the color correction filter. Examples are CONTEXT MANAGER and RAF LOAD TARGET. Deinstall these programs and the Color Service in reverse order. If the Color Service encounters a fatal error it will log this error in the system log and attempt to deinstall itself. If this is not possible for the reason explained in the previous paragraph, then the Color Service will deactivate itself and wait until it can deinstall itself (e.g. until you deinstall Context Manager by logging out). When the Color Service encounters this condition it changes its partition name from "ColorService" to "ColorServic*". LIMITATIONS - The COLOR UTILITIES have been tested with CTOS II 3.3.x, CTOS/XE x3.3, STD-SW 12.1.x, VAM 3.3.0 and CONTEXT MANAGER II 4.0.3. The Color Correction Filter may require modification when using other releases. - Occasionally, the Color Correction Filter cannot prevent the color values stored in a partition's ASCB being changed to 4 times the first two colors. When this happens you can correct the colors using the Color Service's ACTION keys to change the colors back to the colors defined in a specific color palette. COLOR API Thru the 12.1.11 CTOSKrivabo.Lib package several programatic interfaces are available to add color to your applications in an easy way. These programatic interfaces are described below: GetColorPalette (pbFileSpec, cbFileSpec, pbPassword, cbPassword, iPal,pBuf, sBuf, pClrStateRet): ercType GetColorPalette verifies the validity of the specified color configuration file and returns the requested color palette. pbFileSpec describe a character string of the cbFileSpec following form: {Node}[Volume]FileName. It contains the file name of the color configuration file. If pbFileSpec or cbFileSpec are 0, then GetColorPalette defaults to [sys]ColorConfig.sys. pbPassword describe the volume, directory, or cbPassword file password that authorizes access to the specified file. iPal is the number of the color palette to be returned pBuf describe a memory area that is used sBuf by GetColorPalette to read the Color Configuration file. This area must be word-aligned and a multiple of 512 bytes. If pBuf = 0, sBuf bytes of long-lived memory will be allocated temporarily. If pBuf = 0 and sBuf = 0FFFFh, GetColorPalette determines the size of the memory area in function of the memory that is still free. pClrStateRet points to a memory area where the ClrState information will be returned. The format of the returned information is shown below. Note that pRgPal and sRgPalMax should be set prior to calling GetColorPalette. Size Offset Field (bytes) Description ------ --------- ------- ------------------------------ 0 pRgPal 4 describe the memory area where the color palette will be 4 sRgPalMax 2 returned. If pRgPal and sRgPalMax are both 0, then only bPalType, sPal and cPal are returned. If only pRgPal = 0, then sRgPalMax bytes of short-lived memory will be allocated. If sRgPalMax = 0FFFFh, then GetColorPalette determines the correct value for sRgPalMax. If sRgPalMax < sPal, then the color palette is truncated and ercReturnDataAreaTooSmall (erc 39) is returned. 6 bPalType 1 is currently always 3 indicating that color palette corresponds to the Three- Palette Format. 7 sPal 2 is the size of the palette returned. 9 cPal 2 is the number of color palettes in the color configuration file. 11 ercDetail 2 when GetColorPalette returns ercInconsistency (erc 3) then ercDetail contains a more detailed error code. ErcDetail can have the following values: - ercBadFile (200) when the specified color configuration is not a color configuration file or it is corrupt. - ercPaletteOutOfRange (599) when iPal >= cPal. 13 reserved 9 currently not used InitColor (pbFileSpec, cbFileSpec, pbPassword, cbPassword, iPal, fNoBackg2, bColorMode, fNoColorExit): FlagType InitColor verifies the validity of the specified color configuration file and changes the screen colors conforming to the requested color palette. Graphics colors are disabled and the background colors correspond to the Background1 palette. InitColor does not return an error code. When an error occurs, an error message is printed to the video or other device as specified by the NPrint and PutChar operations, and the program is terminated. If you want to nationalize the error messages, copy the file CTOSKrivaboLibMsg.txt to your message file and modify the messages as needed. InitColor returns TRUE when the workstation supports color and FALSE if the workstation does not support color and fNoColorExit is FALSE. InitColor also may be used for programs running on an XE530 thru CLUSTER VIEW. As a program running thru CLUSTER VIEW cannot determine whether the workstation supports color and background color, color and background color support are assumed when your .user file contains the following entries: :ClusterViewColor:Yes :ClusterViewBackgroundColor:Yes If you want to nationalize these two strings, copy the file CTOSKrivaboLibMsg.txt to your message file and modify the messages as needed. Note: As CTOS/XE actually does not support color, this feature cannot be guaranteed for 100%. If you ever get problems when running your color programs on an XE530, then you should remove the above strings from your .user file or replace the Yes string by a No string. pbFileSpec describe a character string of the cbFileSpec following form: {Node}[Volume]FileName. It contains the file name of the color configuration file. If pbFileSpec or cbFileSpec are 0, then InitColor defaults to [sys]ColorConfig.sys. pbPassword describe the volume, directory, or cbPassword file password that authorizes access to the specified file. iPal is the number of the color palette to be used when changing the screen colors. fNoBackg2 TRUE should be used when your application does not use the Background2 palette. It means that the Background2 palette will be set to all zero's. bColorMode specifies whether the color changes are temporary are permanent. The allowed values are: Code Meaning ---- ---------------------------------------------- 0 The color changes are permanent. The ASCB.rgbColorBytes and ASCB.bBackground fields are updated with the new color values. When the program exits to the EXECUTIVE, these colors remain and the color changes do not cause the EXECUTIVE to reinitialize the screen. 1 The color changes are temporary. The ASCB is not updated and the current colors are not saved. 2 The color changes are temporary. The ASCB is not updated. Prior to changing the colors the current colors are saved. When the program exits to the EXECUTIVE, these color changes do not cause the EXECUTIVE to reinitialize the screen. If you use this value, you should call RestoreColorPalette before terminating the program. fNoColorExit For worksations that do not support color, TRUE means that the program is to be terminated with an error message and FALSE means that InitColor should not terminate the program but return FALSE. LoadColorPalette (pbFileSpec, cbFileSpec, pbPassword, cbPassword, iPal, fNoBackg2, bColorMode, pRgSdCVStr, sRgSdCVStr, pBuf, sBuf, pClrStateRet): ercType LoadColorPalette verifies the validity of the specified color configuration file and changes the screen colors conforming to the requested color palette. Graphics colors are disabled and the background colors correspond to the Background1 palette. LoadColorPalette is similar to InitColor, except that LoadColorPalette returns an error code when an error occurs instead of terminating the program with an error message. Further, you can specify the ':FieldName:' strings for which your .user file should be searched in case the program is running on an XE530 thru CLUSTER VIEW. As a program running thru CLUSTER VIEW cannot determine whether the workstation supports color and background color, color and background color support are assumed when your .user file contains the following entries: :FieldName1:Yes :FieldName2:Yes The FieldName1 (e.g. 'ClusterViewColor') and FieldName2 (e.g. 'ClusterViewBackgroundColor') strings can be specified thru the pRgSdCVStr and sRgSdCVStr parameters. Note: As CTOS/XE actually does not support color, this feature cannot be guaranteed for 100%. If you ever get problems when running your color programs on an XE530, then you should remove the above strings from your .user file or replace the Yes string by a No string. pbFileSpec describe a character string of the cbFileSpec following form: {Node}[Volume]FileName. It contains the file name of the color configuration file. If pbFileSpec or cbFileSpec are 0, then LoadColorPalette defaults to [sys]ColorConfig.sys. pbPassword describe the volume, directory, or cbPassword file password that authorizes access to the specified file. iPal is the number of the color palette to be used when changing the screen colors. fNoBackg2 TRUE should be used when your application does not use the Background2 palette. It means that the Background2 palette will be set to all zero's. bColorMode specifies whether the color changes are temporary are permanent. The allowed values are: 0 The color changes are permanent. The ASCB.rgbColorBytes and ASCB.bBackground fields are updated with the new color values. When the program exits to the EXECUTIVE, these colors remain and the color changes do not cause the EXECUTIVE to reinitialize the screen. 1 The color changes are temporary. The ASCB is not updated and the current colors are not saved. 2 The color changes are temporary. The ASCB is not updated. Prior to changing the colors the current colors are saved. When the program exits to the EXECUTIVE, these color changes do not cause the EXECUTIVE to reinitialize the screen. If you use this value, you should call RestoreColorPalette before terminating the program. pRgSdCVStr is the memory address of an array of sRgSdCVStr two string descriptors. Each element of the array describes a ':FieldName:' entry for which your .user file will be searched when the program is running on XE530 thru CLUSTER VIEW. In your .user file these entries may be followed by a Yes, No or Null string. Color support is assumed when the first entry has a Yes value and Background Color support is assumed when the second entry has a Yes value. The colons should not be given as part of the field names. String descriptors are 6-byte blocks of memory. The first 4 bytes contain the memory address of the string; the last two bytes contain the string size. pBuf describe a memory area that is used sBuf by LoadColorPalette to read the Color Configuration file. This area must be word-aligned and a multiple of 512 bytes. If pBuf = 0, sBuf bytes of long-lived memory will be allocated temporarily. If pBuf = 0 and sBuf = 0FFFFh, LoadColorPalette determines the size of the memory area in function of the memory that is still free. pClrStateRet points to a memory area where the ClrState information will be returned. The format of the returned information is shown below. Note that pRgPal and sRgPalMax should be set prior to calling GetColorPalette. Offset Field (bytes) Description ------ --------- ------- ------------------------------ 0 pRgPal 4 describe the memory area where 4 sRgPalMax 2 the color palette will be returned. If pRgPal and sRgPalMax are both 0, then only bPalType, sPal and cPal are returned. If only pRgPal = 0, then sRgPalMax bytes of short-lived memory will be allocated. If sRgPalMax = 0FFFFh, then LoadColorPalette determines the correct value for sRgPalMax. If sRgPalMax < sPal, then the color palette is truncated and ercReturnDataAreaTooSmall (erc 39) is returned. 6 bPalType 1 is currently always 3 indicating that color palette corresponds to the Three- Palette Format. 7 sPal 2 is the size of the palette returned 9 cPal 2 is the number of color palettes in the color configuration file. 11 ercDetail 2 when LoadColorPalette returns ercInconsistency (erc 3) then ercDetail contains a more detailed error code. ErcDetail can have the following values: - ercBadFile (200) when the specified color configuration is not a color configuration file or it is corrupt. - ercPaletteOutOfRange (599) when iPal >= cPal. 13 reserved 9 currently not used RestoreColorPalette : ercType RestoreColorPalette restores the original color palette if it has been saved previously. The original color palette is saved when you call the InitColor or LoadColorPalette operations with bColorMode = 2. RestoreColorPalette is used to restore the original colors prior to terminating the program. It avoids that the EXECUTIVE reinitializes the video because of the color changes and as such removes the programs last video output from the screen. COMMANDS /Color Configure [Color config file] /Color Setup [Color palette number] [Color config file] /Install Color Service [Color config file] [Enable ACTION-key (65h or 'e')] [Foreground ACTION-key (66h or 'f')] [Background ACTION-key (72h or 'r')] [Color cycle ACTION-key (2Bh or '+')] [Activate color correction filter?] [Signon color palette number (0)] [Maximum number of partitions (50)] /Deinstall Color Service (InstallColorService with a case value of DC)