OS/2 Shareware BBS: 5 Edit

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / kl.zip / kl.doc < prev next >

Wrap

Text File | 1997-03-18 | 29KB | 589 lines

****************************************************************************** * (c) Copyright International Business Machines Corporation 1994, 1997. * * All rights Reserved. * * * * User's Guide of KL (KEDIT FileList) macro (Ver 2.10) * * * * * * Author: Shintaroh Hori (Yamato Lab, IBM Japan) * ****************************************************************************** List of files extracted from KL.ZIP ----------------------------------- LICENSE.TXT IBM License Agreement KL.ABS Abstract of this program KL.DOC User's Guide (this file) KL.NEW Change History KL.KEX KL macro KLDIR.KEX Subroutine macro of KL.KEX KLUTIL.DLL REXX functions used by KLDIR.KEX KLPROF.SMP Sample KL profile. Rename to KLPROF.KL to use. KL.CMD Sample CMD to invoke KL.KEX from OS/2 command line. ProfileQ.KEX (To be used with KL.CMD) KLRing.KEX KEDIT Ring List macro for KL. KLMouse.KEX KL Mouse macro for KL KLMouse.DOC Guide to KL Mouse macro KL140L.ZIP KL macro programs for users of KEDIT v5.00P1 or earlier. If your KEDIT is older than V5.00P2, use KL.KEX, KLDIR.KEX, and KLPROF.SMP in this ZIP file. Introduction ------------ KL macro is designed to provide functions similar to what are given by FILELIST EXEC in CMS environment and by OS2FL program on OS2TOOLS disk. KL macro displays a list of information about files that meet file specifier given to the macro as an argument. The list is displayed in a KEDIT file called "KL list", so you can use KEDIT subcommands to manipulate the list itself. Like FL.EXE of OS2FL package, you can issue an OS/2 command typed in Cmd_Area of KL list against the file by pressing an 'Execute' key. You can also issue KL unique commands from the list to sort the list, to refresh the list, and so on. Unlike the FILELIST EXEC, a KL list is added to a current KEDIT ring whenever KL macro is invoked to list files. You can have multiple KL list files on the ring. Default length of filename field and extension field in a KL list is 20 and 8, respectively. They can be customized by an KL profile. You can also change length of the fields locally by executing "/C" command from the KL list or "KL /C" command from KEDIT command line. You can use "/CG" KL command or "KL /CG" command to make a global change in the current KEDIT session. See "Valid KL commands" for more detail. File date is either in yyyy-mm-dd or in yy-mm-dd formats, and File time is either in hh:mm:ss or in hh:mm formats. They can be customized by the KL profile. If an user exit macro is specified by INITEXIT record of KL Profile, KL calls the exit macro just after a list of files are presented or refreshed. (See KL Profile section of this file.) Advantages of KL macro over KEDIT's DIR command ----------------------------------------------- 1. You can type any OS/2 command string or KEDIT subcommand and execute against a file displayed in KL list. In case of DIR command, you need to DEFINE the command *globally*. You can use "=" to repeat the command against some other files on KL list, which cannot be done from dir.dir file in DIR command. 2. You can assign a key to issue a command against a file in KL list by KEDIT's DEFINE command. By checking a return code from KL macro, you can define the key to act only in KL list. (See #3 of "Installation" section for detail.) 3. You can have multiple KL lists on a KEDIT ring. DIR command can open ONLY ONE list file on the KEDIT ring. 4. KL macro can list files that have Hidden and/or System attributes set on, but DIR command cannot. KL macro also displays file attributes, but DIR command does not. 5. KL macro can list files and subdirectories under a given path by /D option, but DIR command cannot. 6. KL macro supports for file specification of UNC format used in IBM LAN Server. 7. Path information on listed files is displayed on top of KL list, while DIR command lists the one on the right side in dir.dir file, thus it does not fit in screen width when path of the files get deeper. Installation ------------ 1. Copy KL.KEX and KLDIR.KEX macros under any directory that KEDIT can search for. Copy KLUTIL.DLL to a directory that is listed in LIBPATH statement of your CONFIG.SYS file. 2. (Optional, but strongly recommended) Define an 'Execute' key in your KEDIT profile. It is defined as follows: DEFINE key_name 'macro KL /ENTER' If you have a KML file to define key assignment while in your profile and want the key_name to work as both the Execute key in KL's session and your original key in non-KL session, insert following line on top of definitions for the key: 'macro KL /ENTER'; if rc \=0 then Exit (rc-1) 'KL /ENTER' does *NOTHING*, but sets Return Code 0 when it is invoked from a non-KL session, and sets Return Code 1 when it is invoked from a KL session, thus behavior of the key in a non-KL list is not modified. 3. (Optional) If you want a key to cause a OS/2 command executed against a file where a cursor is placed on a KL list file, and want the same key to work as usual when in non-KL session, insert following line on top of definitions for the key in your KML file: 'macro KL /EX your_command_string '; if rc \=0 then Exit (rc-1) Example: To define F4 key to upload the file to A-disk of host session A, a part of your KML file for F4 should look as follows; :F4 'macro KL /EX ALMCOPY / HA:= = A'; if rc \=0 then Exit (rc-1) /* your original F4 definitions follow after this ... */ 4. (Optional) You can define keys to retrieve KL commands from a KL command buffer backward or forward when the keys are pressed on a line of KL list, and to retrieve commands from a KEDIT command buffer backward or forward when the keys are pressed on a KEDIT command line. Example: Define C-CURU and C-CURD macros in your KML file as follows; :C-CURU 'macro KL /getcmd -' /*Get KL Cmd BkWrd*/;if rc \=0 then Exit (rc-1) 'sos retrieveB' /* Retrieve cmd from KEDIT cmd line */ Exit :C-CURD 'macro KL /getcmd +' /*Get KL Cmd ForWrd*/;if rc \=0 then Exit (rc-1) 'sos retrieveF' /* Retrieve cmd from KEDIT cmd line */ Exit Note: Though you can use "?n" command on a line of KL list alternatively, these setting are more useful than ?n KL command. 5. (Optional) Create KL profile "KLPROF.KL" on the path specified by DEFPROFILE option of KEDIT, if you want to customize KL macro. See "KL Profile" section for more detail. By setting KLTMP value in your KL profile to a directory on your VDISK, you could make a performance up of KL macro. 6. (Optional) There are some usefull macros and a CMD file included in KL.ZIP file. They are not required for KL macro function, but usability of KL macro will be enhanced by them. For detail, see the last section of this file. Notice on KEDIT profile ----------------------- To use KL macro, it is recommended to issue 'SET REPROFILE ON' in your KEDIT profile. KL macro turns off ID LINE and makes Reserved lines on top of screen by KEDIT SET commands after it opens a list file using your KEDIT profile. If your KEDIT profile does not issue 'SET REPROFILE ON' explicitly, an edit session for a listed file has the same Reserved lines as in the KL list and no ID LINE is displayed when the file is opened from the KL list. This is because KEDIT copies over the values of most SET options from a current file, the KL list file in this case, to a newly opened file. Functions and Command syntax of KL macro ---------------------------------------- ┌──────────────┐ (a) │ ────KL─────┬───────file_spec──────┬────────┬──┴────────────┬────── │ ├──/Dn───┤ │ │ └──/ADD-─┘ │ │ (b) │ ├────────slash_cmd──────────────────────────────┤ │ │ │ (c) │ ├────────/ENTER-────────────────────────────────┤ │ │ │ (d) │ ├────────/EX───cmd_string-──────────────────────┤ │ │ │ (e) │ └────────/GETCMD───sign─────────────────────────┘ Syntax (a): Used to list files that meat a file specification, file_spec. file_spec is a file specifier that is used in OS/2 DIR command's argument. When /Dn, where n should be a number, is specified, search for files and sub-directories is applied to directory tree of n-level under path of the file specifier. If n is omitted, it is default to 256. That is, /D searches all the subdirectories in effect. file_spec may be UNC format like "\\serverid\netname\path" that is used in IBM LAN Server. Note that KEDIT for OS/2 V5.00P3 does not support for editing a file of UNC format. So you need another Editor like TEDIT to edit such file from KL list. If /ADD is used from an existing KL list file, then a list of files is appended to the last line of the KL list file instead of opening a new KL list file on a KEDIT ring. Syntax (b): Used to operate on KL list itself. An example is sorting of the list. slash_cmd is a slash command that is described in the section 'Valid KL command'. Though this command syntax is used from KEDIT command line, slash_cmd itself can be entered in Cmd Area of KL list file and is executed by pressing an Execute key. Syntax (c): It causes 'Execute Action' so that any KL commands typed from Cmd Area of the KL list be executed from top to bottom of the list. It's better to define an Execute key in processing KEDIT profile as as described in the section 'Installation'. For detail on 'Execute Action', see 'Issuing KL commands from a KL List' section.) Syntax (d): Used to assign a key a pre-defined KL command and to invoke the command by pressing the key. When the key is pressed on a line of the list, cmd_string is executed as if cmd_string is typed on the line and an Execute key is pressed. It's useful to assign some keys commands that you use frequently. (See also the step 3 of the section 'Installation'.) KL macro of this syntax does NOTHING when invoked from KEDIT command line. Syntax (e): Used to assign a key to retrieve previous KL command backward or forward from a KL command buffer when the key is pressed on a line of KL list. sign should be "+" to retrieve forward, and anything else to do backward. Note: KL macro of syntax (b), (c), (d), and (e) does NOTHING but sets return code 0 if it is NOT invoked from a KL list file, and sets 1 if it is. ---------------------------------------- When KL macro of syntax (d) and (e) is invoked from a KEDIT command line, it also sets return code 0 without anything. You can use RC from KL macro to get around KEDIT's global definition of keys. (See step 2, 3, and 4 in the section 'Installation'.) Layout of a KL list file ------------------------ (a) File Specifier line: File Specifier line is displayed on top of screen of the list file as KEDIT reserved line(s). The line starts with '#N=' followed by the file specifier given to the KL macro. N is a one-digit number starting from 1 through 9. When KL is invoked with /ADD option from a list file of KL, a list of files for the specifier is appended to the last line of the KL list instead of opening a new list file, and another File Specifier line is added below the last File Specifier Line. (Refer to Syntax (a) of KL macro.) (b) Field description line: Field description line is also displayed below the last File Specifier line as a KEDIT reserved line to show items of information about listed files. (c) Information lines: Information lines are put in a file area, and each line consists of a command space('Cmd Area') and information fields of the listed files. The fields are FileName, Extension, Attribute, Size, DateTime, Specifier_ID, and Relative_Path, from left to right. Default length of FileName and Extension fields are 20 and 8, respectively (It can be changed by a KL Profile.) If length of name of a file is longer than the FileName length, it is truncated to fit in its space with the last character replaced with an asterisk('*'). The same is true for extension of a file. When your OS/2 is DBCS version, the truncation may also occurs at the second last character. Therefore the truncation sring looks like '*', '**', or ' *'. Date format of DateTime field is yyyy-mm-dd by default. It can be changed to yy-mm-dd format by the KL profile. Time format of DateTime field is hh:mm:ss by default. It can be changed to hh:mm format by the KL profile. Specifier_ID for a file points to a File Specifier line, which indicates a home path of the file, that is, a drive and subdirectory part of the file specifier. (Home path is a terminology used in this DOC.) Relative_Path indicates path of the file under the home path. This field is blank when the KL list is shown without /D option. Path of a file in the list can be identified by home path and Relative_Path. (d) KEDIT command line: KEDIT command line is given at bottom of the list file. Issuing KL commands from KL List -------------------------------- You can issue KL command, that is, DOS command, OS/2 command, and/or KL specific command, directly from an information line of the list. You do this by typing the command from Cmd Area of the line, and then pressing an Execute key. (Instead of the Execute key, you may issue "KL /ENTER" from KEDIT's command line.) Even if the command is longer than Cmd Area field, you can just continue typing over the information on the line. Maximum command length that you can type is twice of physical screen width. (When the width is 80, the maximum is 160.) Note, however, that you *MUST NOT* make such modifications of the information in the line as follows: 1) To delete all the characters right to the end of the command string. In default KEDIT setting, it can be done by Ctrl-END key. 2) To change field position of the information in the line by DEL key or INSERT key, for example. This is because the KL macro maintains the same information also at column position starting at (2*physical_screen_width +1). A command string may contain slash character sequence to represent a drive letter, file name, file extension, and so on, just like FILELIST EXEC or FL.EXE. (See the section 'Slash Substitution' for more detail.) If a KEDIT command line includes a command when an Execute key is pressed, the command is executed(after execution of prefix commands if existed in a prefix command area, which is turned off by KL default,) and any KL commands are NOT executed even if they are typed in the list. To execute the KL commands, press the Execute key again. If there is no KL commands typed in the list, pressing the Execute key moves a cursor to a KEDIT command line. (If a prefix command existed in a prefx command area, then it is executed.) When a KL command other than '=' and '?n' is executed, the KL command is put into a retrieve buffer for a current KL list. Up to 20, KL default, of the latest commands are kept in each KL session. The default value can be changed by KL profile. When a command other than KL slash commands is executed from an information line, a current drive and directory are changed to ones for the file in the line before its execution. After the execution, they are restored to the original drive and directory. You can type multiple commands and execute them by pressing an Execute key. In this case they are processed from top to bottom of the list, though it ignores all the commands after a KL slash command, if it is included. (For a KL slash command, See 'Valid KL commands' section.) Note: If a full specification of a file on KL list includes blank characters, be careful to pass the file id to a KL command other than X, KL, and DEL. You will need to enclose the file id with two double-quotes. (For example, type "/" instead of /.) For X, KL, and DEL, the enclosure by two double-quotes is done internally, so you must not type the double-quotes for the KL commands. Valid KL commands ----------------- There are two types of KL commands to be entered in Cmd Area for execution: (a) Slash commands (b) Non-slash commands The first ones operate for KL list file itself, and the second for a file that a KL command is entered for. They are executed by pressing Execute key. Note that they are NOT case sensitive except KL commands which are defined in the KL profile by a user. (a) Slash commands /R ; Refresh a KL list. /RG ; Refresh a KL list with using length of filename and extension fields that have been change by recent /CG command. /C <nl <el>>; Change locally field length of filename and/or extension. /CG <nl <el>>; Change globally field length of filename and/or extension. "/C" changes locally length of filename and/or extension fields in a current KL list to nl and el, respectively. "/CG" makes this change permanent while in the current KEDIT session. If nl and el is not specified, length of both fields get the ones that are set in KL profile. If nl is a whole-number of REXX, a new length is set. If nl is prefixed by a sign(+ or -), the new length is the current length added by the signed nl. When nl is not a whole number, the length is not changed. As for el, it is the same as for nl except that it applies to extension field length. If el is set to 0, filename and extension is *not* splitted in the current KL list. /S<+|->opts ; Sort a KL list by fields specified opts, which is string of characters representing the fields. Valid characters are as follows: N -- Name of the file E -- Extension of the file A -- Attribute of the file S -- Size of the file D -- Date of the file I -- Specifier_ID of the file R -- Relative Path of the file If opts is prefixed by either + or -, sort order is Ascending or Descending, respectively. Default is Ascending. Note: If FELEN is 0 in a KL profile or el is 0 in "/R" command, 'N' specifies both filename and extension, and 'E' gets meaningless. /F<+|-> ; Move to a normal file on the Ring. Option '+', default, indicates Forward, and '-' Backward. /L<+|-> ; Move to a KL list file on the Ring. Option '+', default, indicates Forward, and '-' Backward. /Q ; Quit from KL List session (b) Non-Slash commands = ; Execute a last command for the file ? ; Retrieve a last command string ?n ; Retrieve a command string n times before. ( ?1 = ? ) X dirfile ; Open the file that is added to a KEDIT Ring if dirfile is not a directory. If so, a new KL list is created for the directory. (XEDIT, K, or KEDIT can also be used instead of X.) KL dirfile ; Open a new KL list file with dirfile as an argument of the KL macro, even if dirfile indicates a file. MAC macstr ; Character string of macstr after slash substitution is executed as a KEDIT macro from the KL list file. (MACRO can also be used instead of MAC.) Example: mac msg /d/p will display character string after slash substitution is made for /d/p in KEDIT message area. Useful to check if the substitution is what you expect or not. mac cmsg /d/p/n will put character string into KEDIT command line after slash substitution is made for /d/p/n. R ; Rename the file or the directory. (REN can also be used.) DEL ; Delete the file or Remove the directory. (DELETE can also be used.) DOS cmdstr ; Execute cmd for the file via Kedit's DOS command DOSN cmdstr ; Execute cmd for the file via Kedit's DOSNowait command DOSQ cmdstr ; Execute cmd for the file via Kedit's DOSQuiet command Any other character string that are not defined above or in KLCMD records of the KL profile are executed through Kedit's DOSNowait command, which is a default of KL.KEX and can be changed by the profile. Slash Substitution ------------------ If a command string typed from Cmd Area of KL list include following slash character sequence and an Execute key is pressed, a Slash Substitution is made in the strings and then the substituted strings will be executed. The slash character sequence and its definition is as follows. /N ; file name of the file /E ; file extension of the file /F ; file name of the file with extension /D ; drive letter of the file or "\\" for UNC specification /H ; home path specification of the file (*1) /P ; path specification of the file (*1) /R ; RelDir specification of the file (*1) /O ; escape substitution sequence // ; substitute a slash character(/) / ; full specification of the file (*2) Note: *1 It always ends with '\'. *2 No blank after a single slash is required. When a slash is followed by character string that does not begin with N, E, F, D, H, P, R, O, or another slash(/), then the string is concatenated to the full specification of the file. When there is no slash characters in the command string, a blank and a slash character are appended to the end of the string before the substitution. If you do not want the blank and the slash to be appended to the command string, place /O anywhere in the command string. KL Profile ---------- You can change some of KL default settings by creating your KL profile "KLPROF.KL" on the path specified by DEFPROFILE option of KEDIT command or of KEDIT environment variable. Unless the profile exist on the path, it is not processed by KL macro. Format of the profile is; . Comment line must begin with a semicolon(;). . Non-comment line must take following form: keyword parameter Valid keywords, which is case-insensitive, are as follows: FNLEN ; Sets length of file name field in KL list FELEN ; Sets length of extension field in KL list YEAR2000 ; Date format. 0 for yy-mm-dd. Any others for yyyy-mm-dd. TIMESEC ; Time format. 0 for hh:mm format. Any others for hh:mm:ss. BUFLEN ; Sets number of entries in a retrieve buffer for each KL session. XMODE ; Changes a default shell command DOSNowait for non-slash KL commands to whatever you specified. It would be DOS, DOSNowait, DOSQuiet, or your KEDIT macro name that acts as a shell like DOS/DOSN/DOSQ commands. INITEXIT ; Specifies an User's Exit that KL macro calls after a list of files is displayed. Parameter should be a valid KEDIT command or macro. The User Exit is also called when /R KL command is executed. KLCMD ; Defines a new KL command that can be invoked from KL list. Parameter for KLCMD keyword is a new KL command name followed by blank(s) and a real command string which will be executed as a KEDIT command. If you append a semi-colon(;) to the end of the command string and an another string follows after the semi-colon, the string is treated as a 'trailing option' for the KL command. The trailing option is dynamically appended to arguments to the KL command when it is executed from KL list. Typical example of its use is a re-direct of output from the KL command to NUL device. (See 'cp' KL command in KLprof.smp file in the package.) Note that the new KL command is Case-Sensitive. RSVLINE ; Displays an additional reserved line in a KL list file. The Value must be valid operand of 'SET RESERVED' command. Useful to display information of your key assignment in KL list. (There may be multiple RSVLINE lines.) KLTMP ; Specifies a directory of a temporary file that KLDIR macro creates. Path of the directory must be fully specified with starting a drive letter. Otherwise it is assumed to be an environment variable name that specifies the path. If KLTMP is not specified, or KL macro cannot create a temporary file in a directory specified by KLTMP keyword, it tries to use root directory of boot drive and then other local drives. Notes: 1) KL macro does not check validity of parameter for each keyword. 2) If sum of FNLEN and FELEN values exceeds 28, a Field description line would be truncated when screen width is 80 and when year2000=1 and timesec=0 are specified. Other useful staffs for KL macro -------------------------------- 1. KL.CMD (with ProfileQ.kex) These are front-end programs to list files and directories from OS/2 command line. In ProfileQ.kex, "profile.kex" is assumed to be your KEDIT profile macro. If it is not yours, modify it. 2. KLRing.kex This is a KEDIT Ring List macro that lists normal files and KL list files in a newly opened Ring List file. Each line of the file represents a file on the KEDIT ring. A line that has "<KL>" string is for a KL list file on the ring. With this macro you can list files in the ring and switch to a file directly. Operational keys are predefined in the macro, and you do not need modify your KEDIT KML file. Peek header part of the macro for more detail. 3. KLMouse.kex and KLMouse.doc With KLMouse.kex macro installed, you can go through the KEDIT ring backward and forward with clicking on a File Specifier line of KL list by Mouse buttons. See KLMouse.doc for the installation.