OS/2 Shareware BBS: 5 Edit

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

/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / kl.zip / KL140L.ZIP / KL.DOC next >

Wrap

Text File | 1997-03-16 | 20KB | 403 lines

****************************************************************************** * * * User's Guide of KL (KEDIT FileList) macro (Ver 1.4) * * * * * * Author: Shintaroh Hori ( Yamato Lab, IBM Japan ) * ****************************************************************************** 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, so you can use KEDIT subcommands to manipulate the list itself. Like FILELIST EXEC, you can issue an OS/2 command typed in Cmd Area of the 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, the list file is added to a current KEDIT ring whenever the KL is invoked to list files. (You can have multiple KL list files on the ring.) Default field length of File Name and Extension is 20 and 8, respectively. They can be changed by an KL profile. Installation ------------ 1. Copy KL.KEX and KLDIR.KEX macros under any directory that KEDIT can search for. 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. 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 1. 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 commands 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.) 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 in 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 maintain 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-quote. (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. (a) Slash commands /R ; Refresh a KL FileList /S<+|->opts ; Sort a KL list by fields specified opts, which is string of characters representing the fields. Valid characters are 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 R -- Relative Path of the file If opts is prefixed by either + or -, sort order is Ascending or Descending, respectively. Default is Ascending. /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 FileList 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 than defined above are executed through Kedit's DOSNowait command, which is a default of KL macro and can be changed by a KL 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 (e.g. C:, D:, ...) /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 value 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 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. 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.) Notes: 1) KL macro does not check validity of values in KLPROF.KL. 2) If sum of FNLEN and FELEN values exceeds 28, a Field description line would be truncated when screen width is 80. 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.