═══ 1. Introduction ═══ OS/2 PRXUTILS Dynamic Link Library Reference Version 1.00 (c) Copyright Pedagogic Software 1992. All rights reserved. Licensed to AMR, Inc. and all subsidiaries (no fee required). Program and Documentation by W. David Ashley No warranties, guarantees, etc. are implied, and no liability is assumed for the code, examples, DLLs, or documentation. This software is user-supported software and may be freely copied and used by anyone who wishes to do so as long as the following conditions are met: 1. These functions may not be used by any program for which a fee is charged unless the owner of the program has paid the registration fee. 2. If you transmit a copy of this software to another party you must give them the complete unaltered contents of the PRXUTILS.ZIP file. 3. If you make any modifications to these functions you must change the name of the dynamic link library file PRXUTILS.DLL to some other name. If you feel that this program has benefited you, please register it by sending $25.00 (no fee required by AMR, Inc. and all subsidiaries) to: Pedagogic Software W. David Ashley 5 Timberline Dr. Trophy Club, Tx 76262 USA The source code for PRXUTILS can be obtained by sending $75.00 ($25.00 registration + $50.00 source code) to the same address (no fee required by AMR, Inc. and all subsidiaries). If you have questions, comments or suggestions please contact me at the address above (AMR employees may contact me through PROFS, my user ID is Z2277). DESCRIPTION PRXUTILS is a Dynamic Link Library (DLL) which provides the OS/2 REXX programmer with many versatile functions which augment the OS/2 2.0 system supplied REXXUTIL.DLL library. It is a full 32-bit DLL compiled with IBM's C SET/2 compiler using Developer's Workbench for OS/2 2.0. The functionality in this library is continuation of the development begun with Pedagogic Software's REXXUTIL library for OS/2 1.x. Since IBM has chosen to release their version of REXXUTIL.DLL we have eliminated the duplicate functionality from PRXUTILS and added additional functions not found in our original REXXUTIL library. BEFORE YOU BEGIN Before you begin to use this reference, it would be helpful to understand how you can: o Expand the Contents window to see all available topics o Obtain additional information for a highlighted word or phrase o Use action bar choices. HOW TO USE THE CONTENTS When the Contents window is first displayed, some topics have a plus (+) sign beside them. The plus sign indicates that additional topics are available. To expand the Contents window if you are using a mouse, click on the plus sign. If you are using the keyboard, use the Up Arrow () or Down Arrow () key to highlight the topic and press the Plus (+) key. For example, Introduction has a plus sign beside it. To see the complete list of topics, click on the plus sign or highlight that topic and press the Plus key. To view a topic, double-click on the topic (or press the Up Arrow or Down Arrow key to highlight the topic and then press the Enter key). HOW TO OBTAIN ADDITIONAL INFORMATION After you select a topic, the information for that topic is displayed in a window. Highlighted words or phrases indicate that additional information is available. You will notice that certain words in the following section are highlighted. If you are using a mouse, double-click on the highlighted word. If you are using a keyboard, press the Tab key to move to the highlighted word and then press the Enter key. Additional information will be displayed in a pop-up window. In addition, some topics contain graphic elements which may be highlighted. These elements allow you to select the next or previous topic for viewing. The same technique described above is also used to select the graphic elements. HOW TO USE ACTION BAR CHOICES A number of choices are available for managing information presented in this reference. If you want to see more information about these choices, double-click on the name of the choice (or press the Tab key to move to the choice and press the Enter key). Bookmark Allows you to set a placeholder so you can retrieve information of interest to you. (This choice is available from the Services pull-down.) Search Allows you to find occurrences of a word or phrase in the current topic, selected topics, or all topics. (This choice is available from the Services pull-down.) Print Allows you to print one or more topics. (This choice is available from the Services pull-down.) Copy Allows you to copy a topic you are viewing to a file you can edit. (This choice is available from the Services pull-down.) Options Allows you to change the way your Contents window is displayed. TRADEMARKS The following trademarks apply to this reference: o IBM is a registered trademark of International Business Machines Corporation. o Operating System/2 and OS/2 are trademarks of International Business Machines Corporation. o Personal System/2 and PS/2 are trademarks of International Business Machines Corporation. o REXX/2 is a trademark of International Business Machines Corporation. o C Set/2 is a trademark of International Business Machines Corporation. o Developer's Workbench is a trademark of International Business Machines Corporation. ═══ 1.1. Requirements ═══ PRXUTILS requires that you are already running under the following environment: o OS/2 2.0 PRXUTILS was developed and tested using the final releases of IBM OS/2 2.0, IBM C Set/2, and the IBM Developer's Workbench for OS/2 2.0. PRXUTILS will not function on any version of OS/2 1.x. ═══ 1.2. Installation ═══ Copy the PRXUTILS.DLL file to a directory specified in your LIBPATH. Note: If you have a previous copy of PRXUTILS loaded and OS/2 cannot open/replace the file then a copy of the DLL currently resides in memory. Reboot and before executing any REXX/2 cmds that reference PRXUTILS copy the file to your LIBPATH destination. ═══ 1.3. Usage ═══ PRXUTILS is an external function package. To be able to use a PRXUTILS function in a REXX/2 cmd, you must first register the function via the REXX function RxFuncAdd. call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PrxLoadFuncs' The above example would add the PrxLoadFuncs function so that it can be used. The first argument specifies how you wish to refer to the function in you program (its name in the REXX program). The second argument references the name of the PRXUTILS.DLL library (always 'PRXUTILS'). And the third argument references the name of the entry point in the library which contains the code for the function (the name always referenced in this manual when refering to a PRXUTILS function). To drop the function when the application is done execute the following REXX function: call RxFuncDrop 'PrxLoadFuncs' The function name now becomes unknown to the REXX/2 interpreter in all OS/2 processes and will generate a runtime error if used after this point in the program. Refer to IBM Operating System/2 Procedures Language 2/REXX Reference manual for more information on the RxFuncAdd and RxFuncDrop statements. Note: The case of the strings passed to RxFuncAdd and RxFuncDrop are not important. The strings will be converted to all upper case by the REXX/2 interpreter automatically. ═══ 2. How to Read the Syntax Diagrams ═══ The syntax diagrams shows you how to specify a function so that REXX/2 can correctly interpret what you type. Read the syntax diagram from left to right and from top to bottom, starting at the ─ symbol, following the horizontal line (the main path). A line ending with an ─ means that the command syntax is continued. A line starting with an ─ means that the syntax is continued from the previous line. The ─ symbol marks the end of the function syntax. Required parameters are displayed on the main path; optional parameters are displayed below it. Parameters are classified as constants or variables. String constants must be delimited by the standard REXX/2 quotation marks. A function name is a keyword. REXX/2 functions may be either CALLed or referenced as a function entry. Some of the external functions presented here do not return any values. Variables appear in lowercase letters and represent names or values you supply. Include all punctuation shown in the diagram, such as colons, semicolons, commas, quotation marks, and equal signs. Optional Parameters: Optional parameters appear below the main syntax trace line. If specified they must appear in the order listed. Example: ──CALL PrxCopy srcfilespec, destfilespec──┬────────────┬── └──, option──┘ ═══ 3. Function Overview ═══ The descriptions of all functions in the PRXUTILS package follow. They are grouped by their function (file system functions, macro functions, etc.). They are listed in alphabetical order within their function group. The function groups are listed below: o Miscellaneous Functions o Date Manipulation Functions o File System Functions o REXX/2 Macrospace Functions o VIO Interface Functions ═══ 3.1. Miscellaneous Functions ═══ These functions are miscellaneous in nature. The functions in this group are: o PrxLoadFuncs o PrxDropFuncs o PrxUtilVersion ═══ 3.1.1. PrxDropFuncs ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxDropFuncs ═══ ──call PrxDropFuncs── ═══ Parameters - PrxDropFuncs ═══ None. ═══ Return Values - PrxDropFuncs ═══ Always returns a zero-length string. ═══ Notes - PrxDropFuncs ═══ Drops all of the functions in the PRXUTILS.DLL from REXX. After this call all of PRXUTILS's functions will become unknown to the interpreter, including this function. ═══ Example - PrxDropFuncs ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* drop all of PRXUTILS's functions */ call PrxDropFuncs say 'Functions dropped.' ═══ 3.1.2. PrxLoadFuncs ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxLoadFuncs ═══ ──call PrxLoadFuncs── ═══ Parameters - PrxLoadFuncs ═══ None. ═══ Return Values - PrxLoadFuncs ═══ Always returns a zero-length string. ═══ Notes - PrxLoadFuncs ═══ Registers all of the functions in the PRXUTILS.DLL package to REXX. ═══ Example - PrxLoadFuncs ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs say 'Functions loaded.' ═══ 3.1.3. PrexUtilsVersion ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxUtilsVersion ═══ ──ver = PrxUtilsVersion()── ═══ Parameters - PrxUtilsVersion ═══ None. ═══ Return Values - PrxUtilsVersion ═══ Value Definition ver String containing PRXUTILS version info in the form 'x.xx mmm [d]d,yyyy' where o x.xx is the version number o mmm is the month of compliation o dd is the day of compilation (1 or 2 characters) o yyyy is the year of compliation ═══ Notes - PrxUtilsVersion ═══ Returns the version of the PRXUTILS.DLL which is currently running. ═══ Example - PrxUtilsVersion ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs util_version = substr(PrxUtilsVersion(), 1, 4) util_compdate = substr(PrxUtilsVersion(), 6) ═══ 3.2. Date Manipulation Functions ═══ These functions manipulate standard REXX/2 date. The functions in this group are: o PrxBaseToDate o PrxDateToBase ═══ 3.2.1. PrxBaseToDate ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxBaseToDate ═══ ─fmtdate = PrxBaseToDateDate(basedate)── or ─fmtdate = PrxBaseToDateDate(basedate, fmtstr)── ═══ Parameters - PrxBaseToDate ═══ Parm Definition basedate The base date to be converted. fmtstr (Optional) The format specifier for fmtdate. The string should contain one of the following values: '' (Null string) The format of fmtdate will the same as the format returned by the REXX/2 builtin function date(). 'L' The format of fmtdate will the same as the format returned by the REXX/2 builtin function date('L'). 'N' The format of fmtdate will the same as the format returned by the REXX/2 builtin function date('N'). 'S' The format of fmtdate will the same as the format returned by the REXX/2 builtin function date('S'). The case of the fmtstr is not important. Note: PrxBaseToDate(basedate) is the same as PrxBaseToDate(basedate, ''). ═══ Return Values - PrxBaseToDate ═══ Value Definition '' (Null string) The conversion was not successful or a parameter was not correct. fmtdate The formatted date string corresponding to the fmtstr. ═══ Notes - PrxBaseToDate ═══ Converts a string containing a standard REXX/2 basedate data type (the same format as the REXX/2 date('b') builtin function returns) to the specified formated date type. ═══ Example - PrxBaseToDate ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* format a base date to the specified format */ fmtdate = RexBaseToDate(725975) /* fmtdate = '27 Aug 1988' */ ═══ 3.2.2. PrxDateToBase ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxDateToBase ═══ ──basedate = PrxDateToBase(datestr)── or ──basedate = PrxDateToBase(datestr, fmtstr)── ═══ Parameters - PrxDateToBase ═══ Parm Definition datestr The formated date string to be converted. fmtstr (Optional) The format specifier for datestr. The string should contain one of the following values: '' (Null string) The format of datestr is the same as the format returned by the REXX/2 builtin function date(). 'L' The format of datestr is the same as the format returned by the REXX/2 builtin function date('L'). 'N' The format of datestr is the same as the format returned by the REXX/2 builtin function date('N'). 'S' The format of datestr is the same as the format returned by the REXX/2 builtin function date('S'). The case of the fmtstr is not important. Note: PrxDateToBase(datestr) is the same as PrxDateToBase(datestr, ''). ═══ Return Values - PrxDateToBase ═══ Value Definition '' (Null string) The conversion was not successful or a parameter was not correct. basedate The basedate corresponding to the datestr. ═══ Notes - PrxDateToBase ═══ Converts a string containing a formated date to the standard REXX/2 basedate data type (the same format as the REXX/2 date('b') builtin function returns). ═══ Example - PrxDateToBase ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the base date of the specified input date */ basedate = RexDateToBase('27 Aug 1988') /* basedate = 725975 */ ═══ 3.3. File System Functions ═══ These functions operate on the OS/2 file system. The functions in this group are: o PrxCopyFile o PrxReadToStem o PrxMoveFile o PrxWriteFromStem ═══ 3.3.1. PrxCopyFile ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxCopyFile ═══ ──CALL PrxCopyFile srcfilespec, destfilespec──┬────────────┬── └──, option──┘ or ──return_code = PrxCopyFile(srcfilespec, destfilespec──┬────────────┬──)── └──, option──┘ ═══ Parameters - PrxCopyFile ═══ Parm Definition srcfilespec Source file specification which could include wildcards. The parameter is NOT case sensitive to REXX/2, but the supplied case will be used by OS/2. destfilespec Destination file specification which could include wildcards. The parameter is NOT case sensitive to REXX/2, but the supplied case will be used by OS/2. option Copy option. 'Append' Append source file(s) to the end of the specified destination file(s) if they exist or to create them if they do not. If this option is not present the default is to create/replace the destination file(s). The parameter is NOT case sensitive and only the first letter of the option is significant. ═══ Return Values - PrxCopyFile ═══ Returns the return code from OS/2 DosCopy() system API. Some of the possible return codes are: Value Definition 2 ERROR_FILE_NOT_FOUND 3 ERROR_PATH_NOT_FOUND 5 ERROR_ACCESS_DENIED 26 ERROR_NOT_DOS_DISK 32 ERROR_SHARING_VIOLATION 36 ERROR_SHARING_BUFFER_EXCEEDED 108 ERROR_DRIVE_LOCKED 112 ERROR_DISK_FULL 206 ERROR_FILENAME_EXCED_RANGE 267 ERROR_ACCESS_DIRECTORY ═══ Notes - PrxCopyFile ═══ Copy file(s) to the specified destination. All extended attributes are copied as well as the file contents. If the target disk subsystem does not support extended attributes then they are not copied. ═══ Example - PrxCopyFile ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* copy all files from c:\temp to c:\work */ dest = 'c:\work' return_code = PrxCopyFile('c:\temp\*.*', dest) ═══ 3.3.2. PrxMoveFile ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMoveFile ═══ ──CALL PrxMoveFile oldfilename, newfilename── or ──retc = PrxMoveFile(oldfilename, newfilename)── ═══ Parameters - PrxMoveFile ═══ Parm Definition oldfilename The name of the file or directory to move/rename. The parameter is NOT case sensitive to REXX/2, but the supplied case will be used by OS/2. newfilename The new name of the file or directory. The parameter is NOT case sensitive to REXX/2, but the supplied case will be used by OS/2. ═══ Return Values - PrxMoveFile ═══ Returns the return code from the OS/2 DosMove() API. Some of the possible return codes are: Value Definition 2 ERROR_FILE_NOT_FOUND 3 ERROR_PATH_NOT_FOUND 5 ERROR_ACCESS_DENIED 17 ERROR_NOT_SAME_DEVICE 26 ERROR_NOT_DOS_DISK 32 ERROR_SHARING_VIOLATION 36 ERROR_SHARING_BUFFER_EXCEEDED 108 ERROR_DRIVE_LOCKED ═══ Notes - PrxMoveFile ═══ Move/rename specified file(s) or directory(s) which could include wildcards. ═══ Example - PrxMoveFile ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs call PrxMoveFile 'c:\config.sys', 'config.old' ═══ 3.3.3. PrxReadToStem ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxReadToStem ═══ ──CALL PrxReadToStem filename, stem── or ──return_code = PrxReadToStem(filename, stem)── ═══ Parameters - PrxReadToStem ═══ Parm Definition filename The name of the file to read. The parameter is NOT case sensitive. stem A constant or expression that evaluates to the name of the stem to place the file in. Note: stem.0 will contain the number of lines read. ═══ Return Values - PrxReadToStem ═══ Value Definition '0' The file was read to the specified stem variables successfully. Note: stem.0 is valid only on this return code. '1' Memory error. '2' REXX variable pool error. '3' Error opening or reading the file. ═══ Notes - PrxReadToStem ═══ Reads a specified file into a stem variable. The maximum input line is restricted to 999 characters. If the input line is longer than 999 characters then it will be split physically as many times as necessary into successive stem variables. ═══ Example - PrxReadToStem ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs call PrxReadToStem 'c:\config.sys', 'file' say 'The number of lines in the file is' file.0'.' say 'The listing of the file follows:' do num = 1 to file.0 say file.num end ═══ 3.3.4. PrxWriteFromStem ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWriteFromStem ═══ ──CALL PrxWriteFromStem filename, stem, num──┬─────────────────────┬── └──, start──┬─────────┤ └──, opt──┘ or ──retc = PrxWriteFromStem(filename, stem, num──┬─────────────────────┬──)── └──, start──┬─────────┤ └──, opt──┘ ═══ Parameters - PrxWriteFromStem ═══ Parm Definition filename The name of the file to write. The parameter is NOT case sensitive. stem A constant or expression that evaluates to the name of the file stem variable containing the lines to be written. num The number of lines to write (usually stem.0) start (optional) The line number to start with. The default is 1. opt (optional) Any one of the following: 'Append' Append the stem variables to the specified file. Create a new file if the specified file does not exist. 'Replace' (default) Replace the file specified with the stem variable(s). Create a new file if specified file does not exist. The parameter is NOT case sensitive and only the first letter of the option is significant. ═══ Return Values - PrxWriteFromStem ═══ Value Definition '0' The specified stem variables were written to the file successfully. '1' Memory error. '2' REXX variable pool error. '3' Error opening or writing the file. ═══ Notes - PrxWriteFromStem ═══ Writes a specified file stem variable array to a specified file. ═══ Example - PrxWriteFromStem ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs file.1 = 'First line to be written.' file.2 = 'Second line.' file.3 = 'Last line to be written.' file.0 = 3 call PrxWriteFromStem 'c:\output.txt', 'file', file.0, 1, 'A' /* 3 lines have been appended to the file 'c:\output.txt' */ ═══ 3.4. REXX/2 Macrospace Manipulation Functions ═══ These functions manipulate the REXX/2 macrospace. The functions in this group are: o PrxMacroDrop o PrxMacroErase o PrxMacroLibDir o PrxMacroLoad o PrxMacroQuery o PrxMacroReOrder o PrxMacroSave ═══ 3.4.1. PrxMacroDrop ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroDrop ═══ ──retc = PrxMacroDrop(funcname)── ═══ Parameters - PrxMacroDrop ═══ Parm Definition funcname Name of the Macrospace function to drop. ═══ Return Values - PrxMacroDrop ═══ Value Definition 0 Function successfully dropped from the Macrospace. 2 Function not found in the Macrospace. ═══ Notes - PrxMacroDrop ═══ Drops the specified function from the REXX/2 Macrospace. ═══ Example - PrxMacroDrop ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* drop the function 'TestIt' from the REXX/2 Macrospace */ retc = PrxMacroDrop('testit') ═══ 3.4.2. PrxMacroErase ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroErase ═══ ──retc = PrxMacroErase()── ═══ Parameters - PrxMacroErase ═══ None. ═══ Return Values - PrxMacroErase ═══ Value Definition 0 Macrospace successfully cleared. 2 Macrospace is currently empty. ═══ Notes - PrxMacroErase ═══ Drops all functions unconditionally from the REXX/2 Macrospace. Note: Be very careful in the use of this function. The REXX/2 Macrospace is global to all threads, tasks, and screen groups in OS/2. Functions will be dropped even though other tasks may be currently using them. ═══ Example - PrxMacroErase ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* erase all functions from the Macrospace */ retc = PrxMacroErase() ═══ 3.4.3. PrxMacroLibDir ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroLibDir ═══ ──retc = PrxMacroLibDir(filename, stem)── ═══ Parameters - PrxMacroLibDir ═══ Parm Definition filename The name of the REXX/2 Macro Library file. The parameter is NOT case sensitive. stem A constant or expression that evaluates to the name of the stem variable to place the function directory. The format of each function directory entry is 1. Function size in bytes - 8 characters 2. 1 blank character 3. Function search position - 6 characters 4. 1 blank character 5. Function name - up to 255 characters Note: stem.0 will contain the number of function entries in the library on a successful return from PrxMacroLibDir. ═══ Return Values - PrxMacroLibDir ═══ Value Definition '0' File read was successful. Note: stem.0 is valid only on this return code. '1' Memory error. '2' REXX variable pool error. '5' File open or read error. ═══ Notes - PrxMacroLibDir ═══ Reads the Function Directory of a REXX/2 Macro Library file into a stem variable. ═══ Example - PrxMacroLibDir ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs retc = PrxMacroLibDir('mylib.rxl', 'func') if retc = 0 then do say 'The number of function entries is' func.0'.' say 'The function directory follows:' do num = 1 to func.0 say func.num end end else say 'Invalid return code. Return code =' retc ═══ 3.4.4. PrxMacroLoad ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroLoad ═══ ──retc = PrxMacroLoad(filename)── or ──retc = PrxMacroLoad(filename, fname, srch)── ═══ Parameters - PrxMacroLoad ═══ Parm Definition filename REXX/2 Macro Library or REXX/2 function file name. The parameter is NOT case sensitive. fname Function name to give to the Macrospace function. srch Either of the following literal strings to specify the search order position of the function: 'BEFORE' Load function at beginning of Macrospace search list. 'AFTER' Load function at end of Macrospace search list. The parameter is NOT case sensitive. ═══ Return Values - PrxMacroLoad ═══ Value Definition 0 Function(s) successfully loaded. 1 No memory storage available or memory error. 2 Macro function not found. 4 Macro function already exists in Macrospace. None of the specified functions have been loaded. 5 Macro file error. 6 Macro library file signature error. 7 Macro function source file not found. 8 Invalid search position specified. ═══ Notes - PrxMacroLoad ═══ Loads either a REXX/2 Macro Library or a REXX/2 Function to the REXX/2 Macrospace. The 1 argument version loads all functions from a REXX/2 Macrospace Library and the 3 argument version loads a REXX/2 command file as a function. ═══ Example - PrxMacroLoad ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* load a single REXX/2 function file into the Macrospace */ retc = PrxMacroLoad('func.cmd', 'myfunc', 'BEFORE') ═══ 3.4.5. PrxMacroQuery ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroQuery ═══ ──retc = PrxMacroQuery(funcname)── ═══ Parameters - PrxMacroQuery ═══ Parm Definition funcname Function name in the Macrospace to be searched for. ═══ Return Values - PrxMacroQuery ═══ Value Definition 0 Function not found. 1 Function found. Search order for the function is 'BEFORE'. 2 Function found. Search order for the function is 'AFTER'. ═══ Notes - PrxMacroQuery ═══ Queries the REXX/2 Macrospace for the existence of a function. ═══ Example - PrxMacroQuery ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* query Macrospace for function 'myfunc' */ retc = PrxMacroQuery('myfunc') ═══ 3.4.6. PrxMacroReOrder ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroReOrder ═══ ──retc = PrxMacroReOrder(fname, srch)── ═══ Parameters - PrxMacroReOrder ═══ Parm Definition fname Function name in the Macrospace to be altered. srch Either of the following literal strings to specify the search order position of the function: 'BEFORE' Set function at beginning of Macrospace search list. 'AFTER' Set function at end of Macrospace search list. The parameter is NOT case sensitive. ═══ Return Values - PrxMacroReOrder ═══ Value Definition 0 Function search option successfully altered. 2 Function not found. 8 Invalid search option specified. ═══ Notes - PrxMacroReOrder ═══ Adjusts the search order position of the specified function in the REXX/2 Macrospace. ═══ Example - PrxMacroReOrder ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* adjust search position of function 'myfunc' */ retc = PrxMacroReOrder('myfunc', 'AFTER') ═══ 3.4.7. PrxMacroSave ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxMacroSave ═══ ──retc = PrxMacroSave(filename)── ═══ Parameters - PrxMacroSave ═══ Parm Definition filename Name of the file in which to save the Macrospace. The parameter is NOT case sensitive. ═══ Return Values - PrxMacroSave ═══ Value Definition 0 Function saved in the specified file. 2 REXX/2 Macrospace is empty, no functions loaded or saved. 3 An extension is required on the specified filename. 5 File error. ═══ Notes - PrxMacroSave ═══ Saves the entire REXX/2 Macrospace to the specified filename. ═══ Example - PrxMacroSave ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* save all functions in the Macrospace to the file 'myfuncs.rxl' */ retc = PrxMacroSave('myfuncs.rxl') ═══ 3.5. VIO Interface Functions ═══ These functions call OS/2 system VIO functions to manipulate text screens and windows. The functions in this group are: o PrxGetAnsi o PrxGetCurPos o PrxGetMode o PrxPrtSc o PrxReadCellStr o PrxReadCharStr o PrxScrollDn o PrxScrollLf o PrxScrollRt o PrxScrollUp o PrxSetAnsi o PrxSetCurPos o PrxSetMode o PrxWrtCellStr o PrxWrtCharStr o PrxWrtCharStrAtt o PrxWrtNAttr o PrxWrtNCell o PrxWrtNChar o PrxWrtTTY ═══ 3.5.1. PrxGetAnsi ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxGetAnsi ═══ ──ansi_state = PrxGetAnsi()── ═══ Parameters - PrxGetAnsi ═══ None. ═══ Return Values - PrxGetAnsi ═══ Value Definition '0' ANSI processing is disabled. '1' ANSI processing is enabled. ═══ Notes - PrxGetAnsi ═══ Obtains the current state of the ANSI flag. Note: This function uses VioGetAnsi(). ═══ Example - PrxGetAnsi ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the current ansi state */ ansi_state = PrxGetAnsi() ═══ 3.5.2. PrxGetCurPos ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxGetCurPos ═══ ──curpos = PrxGetCurPos()── ═══ Parameters - PrxGetCurPos ═══ None. ═══ Return Values - PrxGetCurPos ═══ Value Definition 'row col' The row position and then the column position as a single string. ═══ Notes - PrxGetCurPos ═══ Obtains the current cursor position. Note: This function uses VioGetCurPos(). ═══ Example - PrxGetCurPos ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the current cursor position */ curpos = PrxGetCurPos() parse var curpos row column ═══ 3.5.3. PrxGetMode ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxGetMode ═══ ──mode = PrxGetMode()── ═══ Parameters - PrxGetMode ═══ None. ═══ Return Values - PrxGetMode ═══ Value Definition 'type colors cols rows hres vres' The VIOMODEINFO structure as a single string. ═══ Notes - PrxGetMode ═══ Obtains the current screen mode. Note: This function uses VioGetMode(). ═══ Example - PrxGetMode ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the current screen mode */ mode = PrxGetMode() parse var mode type colors cols rows hres vres ═══ 3.5.4. PrxPrtSc ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxPrtSc ═══ ──CALL PrxPrtSc── ═══ Parameters - PrxPrtSc ═══ None. ═══ Return Values - PrxPrtSc ═══ Always returns '' (null string). ═══ Notes - PrxPrtSc ═══ copies the contents of the screen to the printer. Note: This function uses VioPrtSc(). ═══ Example - PrxPrtSc ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* print the current screen */ call PrxPrtSc ═══ 3.5.5. PrxReadCellStr ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxReadCellStr ═══ ──cstr = PrxReadCellStr(num, row, col)── ═══ Parameters - PrxReadCellStr ═══ Parm Definition num The number of character-attribute pairs to read. row The starting row position from which to read. col The starting column position from which to read. ═══ Return Values - PrxReadCellStr ═══ Value Definition cstr The character-attribute string. ═══ Notes - PrxReadCellStr ═══ Copies a character-attribute string from the screen from the specified position. Note: This function uses VioReadCellStr(). ═══ Example - PrxReadCellStr ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the cell string starting at row 4 column 5 for 20 cells */ cstr = PrxReadCellStr(20, 4, 5) ═══ 3.5.6. PrxReadCharStr ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxReadCharStr ═══ ──cstr = PrxReadCharStr(num, row, col)── ═══ Parameters - PrxReadCharStr ═══ Parm Definition num The number of characters to read. row The starting row position from which to read. col The starting column position from which to read. ═══ Return Values - PrxReadCharStr ═══ Value Definition cstr The character string. ═══ Notes - PrxReadCharStr ═══ Copies a string (but not its attribute byte) from the screen from the specified position. Note: This function uses VioReadCharStr(). ═══ Example - PrxReadCharStr ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the string starting at row 4 column 5 for 20 cells */ cstr = PrxReadCharStr(20, 4, 5) ═══ 3.5.7. PrxScrollDn ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxScrollDn ═══ ──CALL PrxScrollDn top, left, bot, right, numlines, fill── ═══ Parameters - PrxScrollDn ═══ Parm Definition top The top line number marking the scroll area (zero-based). left The left column number marking the scroll area (zero-based). bot The bottom line number marking the scroll area (zero-based). right The right column number marking the scroll area (zero-based). numlines The number of lines to scroll. fill The fill character-attribute pair to be used. ═══ Return Values - PrxScrollDn ═══ Always returns '' (null string). ═══ Notes - PrxScrollDn ═══ Scrolls the designated area of the screen downward the specified number of lines. Note: This function uses VioScrollDn(). ═══ Example - PrxScrollDn ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* scroll the first 5 lines of the screen down 2 lines */ /* fill the scrolled area with blanks/white attribute */ call PrxScrollDn 0, 0, 4, 79, 2, ' ' || x2c(07) ═══ 3.5.8. PrxScrollLf ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxScrollLf ═══ ──CALL PrxScrollLf top, left, bot, right, numchars, fill── ═══ Parameters - PrxScrollLf ═══ Parm Definition top The top line number marking the scroll area (zero-based). left The left column number marking the scroll area (zero-based). bot The bottom line number marking the scroll area (zero-based). right The right column number marking the scroll area (zero-based). numlines The number of characters to scroll. fill The fill character-attribute pair to be used. ═══ Return Values - PrxScrollLf ═══ Always returns '' (null string). ═══ Notes - PrxScrollLf ═══ Scrolls the designated area of the screen leftward the specified number of characters. Note: This function uses VioScrollLf(). ═══ Example - PrxScrollLf ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* scroll the first 5 lines of the screen left 20 characters */ /* fill the scrolled area with blanks/white attribute */ call PrxScrollLf 0, 0, 4, 79, 20, ' ' || x2c(07) ═══ 3.5.9. PrxScrollRt ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxScrollRt ═══ ──CALL PrxScrollRt top, left, bot, right, numchars, fill── ═══ Parameters - PrxScrollRt ═══ Parm Definition top The top line number marking the scroll area (zero-based). left The left column number marking the scroll area (zero-based). bot The bottom line number marking the scroll area (zero-based). right The right column number marking the scroll area (zero-based). numlines The number of characters to scroll. fill The fill character-attribute pair to be used. ═══ Return Values - PrxScrollRt ═══ Always returns '' (null string). ═══ Notes - PrxScrollRt ═══ Scrolls the designated area of the screen rightward the specified number of characters. Note: This function uses VioScrollRt(). ═══ Example - PrxScrollRt ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* scroll the first 5 lines of the screen right 20 characters */ /* fill the scrolled area with blanks/white attribute */ call PrxScrollRt 0, 0, 4, 79, 20, ' ' || x2c(07) ═══ 3.5.10. PrxScrollUp ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxScrollUp ═══ ──CALL PrxScrollUp top, left, bot, right, numlines, fill── ═══ Parameters - PrxScrollUp ═══ Parm Definition top The top line number marking the scroll area (zero-based). left The left column number marking the scroll area (zero-based). bot The bottom line number marking the scroll area (zero-based). right The right column number marking the scroll area (zero-based). numlines The number of lines to scroll. fill The fill character-attribute pair to be used. ═══ Return Values - PrxScrollUp ═══ Always returns '' (null string). ═══ Notes - PrxScrollUp ═══ Scrolls the designated area of the screen upward the specified number of lines. Note: This function uses VioScrollUp(). ═══ Example - PrxScrollUp ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* scroll the first 5 lines of the screen up 2 lines */ /* fill the scrolled area with blanks/white attribute */ call PrxScrollUp 0, 0, 4, 79, 2, ' ' || x2c(07) ═══ 3.5.11. PrxSetAnsi ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxSetAnsi ═══ ──CALL PrxSetAnsi state── ═══ Parameters - PrxSetAnsi ═══ Parm Definition '0' Disable ANSI processing. '1' Enable ANSI processing. ═══ Return Values - PrxSetAnsi ═══ Always returns '' (null string). ═══ Notes - PrxSetAnsi ═══ Sets the state of the ANSI flag. Note: This function uses VioSetAnsi(). ═══ Example - PrxSetAnsi ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* set the ansi flag */ call PrxSetAnsi '1' ═══ 3.5.12. PrxSetCurPos ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxSetCurPos ═══ ──CALL PrxSetCurPos row, col── ═══ Parameters - PrxSetCurPos ═══ Parm Definition row The new row position for the cursor (zero-based). col The new column position for the cursor (zero-based). ═══ Return Values - PrxSetCurPos ═══ Always returns '' (null string). ═══ Notes - PrxSetCurPos ═══ Sets the current cursor position. Note: This function uses VioSetCurPos(). ═══ Example - PrxSetCurPos ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* set the cursor position to the top left */ call PrxSetCurPos 0, 0 ═══ 3.5.13. PrxSetMode ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxSetMode ═══ ──CALL PrxSetMode type, colors, cols, rows, hres, vres── ═══ Parameters - PrxSetMode ═══ Parm Definition type The screen mode. colors The number of colors. cols The number of text columns. rows The number of text rows. hres The number of pel columns. vres The number of pel rows. ═══ Return Values - PrxSetMode ═══ Always returns '' (null string). ═══ Notes - PrxSetMode ═══ Sets the screen mode. Note: This function uses VioSetMode(). ═══ Example - PrxSetMode ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* get the current screen mode */ mode = PrxGetMode() parse var mode type colors cols rows hres vres /* change to 43 line mode */ call PrxSetMode type, colors, cols, 43, hres, vres ═══ 3.5.14. PrxWrtCellStr ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtCellStr ═══ ──CALL PrxWrtCellStr cstr, row, col── ═══ Parameters - PrxWrtCellStr ═══ Parm Definition cstr The character-attribute string to write to the screen. row The row position for the string (zero-based). col The column position for the string (zero-based). ═══ Return Values - PrxWrtCellStr ═══ Always returns '' (null string). ═══ Notes - PrxWrtCellStr ═══ Write a character-attribute string to the screen at the specified position. Note: This function uses VioWrtCellStr(). ═══ Example - PrxWrtCellStr ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write cstr to the top left of the screen */ call PrxWrtCellStr cstr, 0, 0 ═══ 3.5.15. PrxWrtCharStr ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtCharStr ═══ ──CALL PrxWrtCharStr str, row, col── ═══ Parameters - PrxWrtCharStr ═══ Parm Definition str The character string to write to the screen. The current screen attributes are used. row The row position for the string (zero-based). col The column position for the string (zero-based). ═══ Return Values - PrxWrtCharStr ═══ Always returns '' (null string). ═══ Notes - PrxWrtCharStr ═══ Write a character string to the screen at the specified position utilizing the current screen attributes. Note: This function uses VioWrtCharStr(). ═══ Example - PrxWrtCharStr ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write str to the top left of the screen */ call PrxWrtCharStr str, 0, 0 ═══ 3.5.16. PrxWrtCharStrAtt ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtCharStrAtt ═══ ──CALL PrxWrtCharStrAtt str, row, col, att── ═══ Parameters - PrxWrtCharStrAtt ═══ Parm Definition str The character string to write to the screen. row The row position for the string (zero-based). col The column position for the string (zero-based). att The attribute for the string. ═══ Return Values - PrxWrtCharStrAtt ═══ Always returns '' (null string). ═══ Notes - PrxWrtCharStrAtt ═══ Write a character string to the screen at the specified position utilizing the specified attribute. Note: This function uses VioWrtCharStrAtt(). ═══ Example - PrxWrtCharStrAtt ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write str to the top left of the screen */ /* use green forground, white background */ call PrxWrtCharStrAtt str, 0, 0, x2c(72) ═══ 3.5.17. PrxWrtNAttr ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtNAttr ═══ ──CALL PrxWrtNAttr attr, num, row, col── ═══ Parameters - PrxWrtNAttr ═══ Parm Definition attr The attribute. num The number of time to write the attribute. row The start row position (zero-based). col The start column position (zero-based). ═══ Return Values - PrxWrtNAttr ═══ Always returns '' (null string). ═══ Notes - PrxWrtNAttr ═══ Writes an attribute the specified number of times to the specified screen position. Note: This function uses VioWrtNAttr(). ═══ Example - PrxWrtNAttr ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write green forground/white background */ /* attribute to the top left of the screen */ /* 60 times */ call PrxWrtNAttr x2c(72), 60, 0, 0 ═══ 3.5.18. PrxWrtNCell ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtNCell ═══ ──CALL PrxWrtNCell cell, num, row, col── ═══ Parameters - PrxWrtNCell ═══ Parm Definition cell The character-attribute to write. num The number of time to write the cell. row The start row position (zero-based). col The start column position (zero-based). ═══ Return Values - PrxWrtNCell ═══ Always returns '' (null string). ═══ Notes - PrxWrtNCell ═══ Write a character-attribute pair to the screen the specified number of times starting at the specified position. Note: This function uses VioWrtNCell(). ═══ Example - PrxWrtNCell ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write character 'A' with green forground/white background */ /* cell to the top left of the screen 60 times */ call PrxWrtNCell 'A' || x2c(72), 60, 0, 0 ═══ 3.5.19. PrxWrtNChar ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtNChar ═══ ──CALL PrxWrtNChar char, num, row, col── ═══ Parameters - PrxWrtNChar ═══ Parm Definition char The character to write. num The number of time to write the character. row The start row position (zero-based). col The start column position (zero-based). ═══ Return Values - PrxWrtNChar ═══ Always returns '' (null string). ═══ Notes - PrxWrtNChar ═══ Write a character to the screen the specified number of times starting at the specified position utilizing the current screen attributes. Note: This function uses VioWrtNChar(). ═══ Example - PrxWrtNChar ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write character 'A' to the top left of the screen 60 times */ call PrxWrtNChar 'A', 60, 0, 0 ═══ 3.5.20. PrxWrtTTY ═══ Select one: Syntax Parameters Return Values Notes Example ═══ Syntax - PrxWrtTTY ═══ ──CALL PrxWrtTTY str── ═══ Parameters - PrxWrtTTY ═══ Parm Definition str The character string to write. ═══ Return Values - PrxWrtTTY ═══ Always returns '' (null string). ═══ Notes - PrxWrtTTY ═══ Write a character string to the screen starting at the current cursor position. Note: This function uses VioWrtTTY(). ═══ Example - PrxWrtTTY ═══ /* add all PRXUTILS functions */ call RxFuncAdd 'PrxLoadFuncs', 'PRXUTILS', 'PRXLOADFUNCS' call PrxLoadFuncs /* write character string to the screen */ call PrxWrtTTY 'This is a test' ═══ 4. Sample REXX/2 CMD using PRXUTILS ═══ The file REXTEST1.CMD is an example of the use of most of the Miscellaneous and File System functions available in the PRXUTILS.DLL package. The file REXTEST2.CMD is an example of the use of the Date Manipulation Functions available in the PRXUTILS.DLL package. The file REXTEST3.CMD is an example of the use of the REXX/2 Macrospace Manipulation Functions available in the PRXUTILS.DLL package. The file REXTEST4.CMD is an example of the use of the VIO Interface Functions available in the PRXUTILS.DLL package. ═══ 5. Support of PRXUTILS ═══ Support and enhancements for PRXUTILS will be performed by the author on an "as time permits" basis. If you have questions, comments or suggestions on improvements the author can be reached at the address below: Pedagogic Software W. David Ashley 5 Timberline Dr. Trophy Club, Tx 76262 USA AMR employees may contact me through PROFS, my user ID is Z2277. ═══ ═══ BookMark When you place a bookmark on a topic, it is added to a list of bookmarks you have previously set. You can view the list, and you can remove one or all bookmarks from the list. If you have not set any bookmarks, the list is empty. To set a bookmark, do the following: 1. Select a topic from the Contents. 2. When that topic appears, choose the Bookmark option from the Services pull-down. 3. If you want to change the name used for the bookmark, type the new name in the field. 4. Click on the Place radio button (or press the Up or Down Arrow key to select it). 5. Click on OK (or select it and press Enter). The bookmark is then added to the bookmark list. ═══ ═══ Search You can specify a word or phrase to be searched. You can also limit the search to a set of topics by first marking the topics on the Contents list. To search for a word or phrase in all topics, do the following: 1. Choose the Search option from the Services pull-down. 2. Type the word or words to be searched. 3. Click on All sections (or press the Up or Down Arrow keys to select it). 4. Click on Search (or select it and press Enter) to begin the search. 5. The list of topics where the word or phrase appears is displayed. If only one topic contains the word or phrase, a window containing that topic appears. ═══ ═══ Print You can print one or more topics. You can also print a set of topics by first marking the topics on the Contents list. To print the document Contents list, do the following: 1. Choose Print from the Services pull-down. 2. Click on Contents (or press the Up or Down Arrow to select it). 3. Click on Print (or select it and press Enter). 4. The Contents list is printed on your printer. ═══ ═══ Copy You can copy a topic you are viewing into a temporary file named TEXT.TMP. You can later edit that file by using the editor of your choice. To copy a topic, do the following: 1. Expand the Contents list and select a topic. 2. When a topic appears, choose Copy to file from the Services pull-down. 3. The system puts the text pertaining to that topic in the temporary TEXT.TMP file. For information on one of the other choices in the Services pull-down, highlight the choice and press the F1 key. ═══ ═══ Options You can control the appearance of the Contents list. To expand the Contents and show all levels for all topics, choose Expand all from the Options pull-down. You can also press the Ctrl and * keys together. For information on one of the other choices in the Services pull-down, highlight the choice and press the F1 key.