1 KCAP KeyCapture does logging of terminal input data. For a full list of KeyCapture commands see KeyCapture Subtopic: Commands. 2 Commands The KeyCapture subcommands are: ATTACH - Attach to another process in you job. EXIT - Exit interactive KeyCapture prompting. FORMAT - Format a log file. HELP - Access on-line KeyCapture help. LICENSE - Enter Product Authorization Key. NODE_NAME_CHANGE - Update licensed nodename after a nodename change. NOTRACK - End KeyCapture logging. QUIT - Exit interactive KeyCapture prompting. RT_ENABLE - (VAX-Only) Enable VAX KeyCapture on an RTA unit. SHOW - Show various KeyCapture data. SHUTDOWN - Shut down KeyCapture - Only use from KCAP_SHUTDOWN.COM. SPAWN - Spawn a subprocess. TRACK - Start KeyCapture logging. As shipped, subcommands may be used as verbs during interactive KeyCapture command prompting (e.g. KCAP> TRACK), but subcommands must be entered as qualifiers when used as part of a single-line DCL command (e.g. $ KCAP/TRACK). This default behavior can be changed. See the KeyCapture Commands Subtopic: /COMMAND_MODE. 3 ATTACH KCAP> ATTACH process_name KCAP> ATTACH/IDENTIFICATION=nnn Used from the KCAP> prompt, the ATTACH subcommand allows one to attach back to another process in one's job, just as with the DCL ATTACH command. You must specify either the process name to attach to, or else you can provide the process ID to attach to with the /IDENTIFICATION=nnn syntax. Example: KCAP> ATTACH JBREWER or KCAP> ATTACH/IDENTIFICATION=6D 3 EXIT KCAP> EXIT The EXIT command is used to exit back to DCL from the interactive command-prompting mode of KeyCapture. !3 FORMAT ! $ KCAP/FORMAT in_file out_file KCAP> FORMAT in_file out_file ! ! The KCAP/FORMAT command may be used to convert the format of KeyCapture ! files so that they may be more easily read. ! ! The KeyCapture FORMAT subcommand converts a log file containing ! KeyCapture sequences (which might otherwise be difficult ! to display, print or analyze) into a more readable format. ! ! Example: ! ! $ KCAP /TRACK /LOG=SMITH.LOG ! Make KeyCapture file. ! $! After a while, exit from KeyCapture... ! $ KCAP /NOTRACK ! Close file. ! ! The output file (SMITH.FMT) will be in a more human-readable ! format. This is useful for typing, printing, or searching. 3 HELP $ KCAP /HELP [topic] [subtopic] KCAP> HELP [topic] [subtopic] Displays on-line help on KeyCapture usage. The help topic and subtopic specify aspects of KeyCapture for which you want further information. You may use the standard VMS wildcard characters * and % (either by themselves or within a topic or subtopic). 3 LICENSE $ KCAP /LICENSE When you put a new version of a licensed NDC product on your system, you will be allowed to demo it for a period of time, after which the product will only continue to work if you are under support or make arrangements with NDC for an extension of the demo. (If you received the product through an NDC distributor then they will be able to help you with licensing.) The KCAP/LICENSE command is used when communicating with NDC concerning your license. NDC can give out license keys to extend demos or record support arrangements. The KCAP/LICENSE command gives you a license key which you pass on to NDC. NDC then gives you back a responding key which you enter, updating the NDC license database on your system for the product. The LMF$KEYCAPTURE.LDB file in KCAP$LOCATION should not be deleted from your system. If it is, then you will need to get a license key from NDC in order to continue to use the product. If you change the KCAP$LOCATION directory on your system, then in order to continue to use the product, you will also need to rename the LMF$KEYCAPTURE.LDB file into the new directory. (If you are not demoing, then you may alternately copy the file to the new directory, instead of renaming it there.) You must have SYSPRV as an authorized privilege to use the license command. The license command first asks you to enter your exact company name. The company name should be entered as you want it to display in the license message which goes to the terminal when running the product. The name, including all spacing and punctuation, must be communicated to NDC exactly or the license key will not be accepted. Once a company name has been exchanged with NDC, the company name cannot thereafter be changed without first consulting with NDC. After entering the company name, you will be given a license key to transmit to NDC. It should be communicated exactly, including the encoding-type, nodename, etc, as directed on the license screen. If you are not communicating the license key to NDC immediately, then you can exit the license screen by entering a Ctrl-Z at the prompt. You may, alternately, create the file KEY.LIS, containing the necessary licensing information for NDC, by pressing the PF4 key, instead of Ctrl-Z. When you receive a responding key from NDC, you should re-enter the company name exactly as before (if you have exited from the license screen meanwhile). Then enter the responding key, exactly as given by NDC. You will get a key-accepted message if all goes well. If there has been any miscommunication of the company name, license key or encoding type, or the responding key, then you will get an error message and will have to try again. 3 NODE_NAME_CHANGE $ KCAP /NODE_NAME_CHANGE If you should change the nodename of a node which is licensed for an NDC product (something we expect would be a very rare occurrence) the product will no longer work on that node unless you then use the NODE_NAME_CHANGE command while running the product from that node. This records the nodename change in the NDC license database on your system. The NODE_NAME_CHANGE command cannot be used to put the product onto a different node than the one originally licensed. If you change a nodename and do not use this command, you will later receive a message telling you that you are running a demo version of the software and that it is about to expire. The NODE_NAME_CHANGE command will prompt you for the old name for the node you are running from, and will change the license record for the current node from the old name you give to the current (new) name for that node. The product may not be in use on the system when this command is used. SYSPRV as an authorized privilege is required to use the NODE_NAME_CHANGE command. 3 NOTRACK $ KCAP/NOTRACK KCAP> NOTRACK The KCAP/NOTRACK subcommand is used to end KeyCapture for a terminal. For more information, see the KeyCapture Commands Subtopic: TRACK. 3 QUIT KCAP> QUIT The QUIT subcommand is used to exit back to DCL from the interactive command-prompting mode of KeyCapture. It is synonymous with the EXIT subcommand. Example: $ KCAP KCAP> QUIT $ 3 TRACK $ KCAP/TRACK [=filespec] KCAP> TRACK [=filespec] The KCAP/TRACK subcommand is used to start KeyCapture for a terminal. TRACK also enables tracking of RTA terminals. You may also specify the name for the resulting KeyCapture file. The default filespec is taken from the logical KCAP$OUTPUT_LOG_FILE. This logical may be defined system-wide by KCAP_DEFAULTS.COM, or it may be defined in any of the logical-name tables specified in LNM$KCAP_TABLE_SEARCH_LIST, which is defined by KCAP_DEFAULTS.COM. See the top-level KCAP Subtopic: Defaults. If this logical is not defined and if /OUTPUT_LOG_FILE is specified without the optional filespec, then KCAP will generate a log file in the SYS$MANAGER directory using a default log-file name of: KCAP_username_terminalname.KCAP To close the current log file and start logging to a new log file use a $ KCAP/TRACK/NEW_FILE command. ! The /REOPEN qualifier also affects KCAP/TRACK. ! Terminal logging with /TRACK is terminated by KCAP/NOTRACK. Examples: $ KCAP /TRACK ! Start KeyCapture for the SYS$COMMAND terminal ! using the default file name and directory. $ KCAP/TRACK=SYS$SCRATCH:SAVE_INPUT ! Start capture specifying a file ! spec. 4 Description Key capture begins after a TRACK command has been done. This is often done from SYLOGIN.COM or LOGIN.COM. KeyCapture is turned off by the NOTRACK command. When KeyCapture is in progress, a new log file can be started with KCAP/TRACK/NEW_FILE. This closes any existing file and starts key capture to a new file. !4 Parameters ! ! You can specify the name of a terminal other than your own for which ! the KeyCapture is to be turned on. ! ! Example: ! ! $ KCAP /TRACK LTA5059 ! Start KeyCapture for LTA5059. !4 Qualifiers !/DISPLAY_TYPE ! ! $ KCAP/TRACK /DISPLAY_TYPE=keyword ! ! Used to chose the format in which control characters ! are displayed in the file. Keywords available are: ! ! CHARACTER - Displays control-characters as-is. ! DISPLAY - Displays control characters in a reverse-video ! character format. 8-bit control characters are ! displayed in reverse-video and underlined. The ! Delete character is displayed as a bold, ! reverse-video lower-case d. ! HEXIDECIMAL - Displays control characters in a reverse video ! format. ! PLAIN_HEX - Displays control characters in format. (Default) ! ! Example: $ KCAP/TRACK/DISPLAY_TYPE=CHARACTER ! ! The above command makes a file of all input keystokes entered ! at the terminal. The keystrokes are put into the log file as-is. ! /MAX_REOPEN $ KCAP/TRACK/REOPEN /MAX_REOPEN = blocks /NOMAX_REOPEN Specifies the approximate maximum number of blocks to which a terminal-logging file may grow before a new version of the log file is started, when /REOPEN is in effect. Use /NOMAX_REOPEN to specify that any default /MAX_REOPEN value should be ignored. The default value for /MAX_REOPEN is taken from the logical KCAP$MAX_REOPEN, usually defined by KCAP_DEFAULTS.COM. Example: $ KCAP/TRACK/REOPEN/MAX_REOPEN=100 For more information, see the KCAP Commands TRACK Subtopic: /REOPEN. /MIN_REOPEN $ KCAP/TRACK/REOPEN /MIN_REOPEN = blocks /NOMIN_REOPEN Specifies the minimum number of blocks to which a terminal- logging file must grow before a new version of the log file is started, when /REOPEN is in effect. Use /NOMIN_REOPEN to specify that any default /MIN_REOPEN value should be ignored. The default value for /MIN_REOPEN is taken from the logical KCAP$MIN_REOPEN, usually defined by KCAP_DEFAULTS.COM. Example: $ KCAP/TRACK/REOPEN/MIN_REOPEN=10 /MIN_REOPEN is ignored for reopens done as a result of a /TIME_OF_DAY specification. For more information, see the KCAP Commands TRACK Subtopic: /REOPEN /NEW_FILE $ KCAP/TRACK /[NO]NEW_FILE Used to specify that a new KeyCapture file should be started. Any current KeyCapture file is closed. Example: $ KCAP/TRACK=LOG.LOG ! Start logging to LOG.LOG. $ KCAP/TRACK=NEWLOG.LOG/NEW_FILE ! Close LOG.LOG and start ! logging to NEWLOG.LOG. /PERMANENT $ KCAP/TRACK /PERMANENT /NOPERMANENT (default) Used to specify that the screen-saving (on AXP) or terminal-logging (on AXP or VAX) cannot be shut off for the terminal concerned. Example: $ KCAP/TRACK/PERMANENT Also applies to terminal-logging on both VAX and AXP. E.g. KCAP> TRACK=PERMANENT.LOG /PERMANENT The PERMANENT qualifier disallows turning off screen-saving with the NOTRACK command. If there is a log file for the screen-saving, then the logging cannot be turned off if /PERMANENT is used. A permanent screen-saver only goes away when the terminal itself goes away (for LTAs etc which are deleted when the user logs off) or when the system is shut down (for permanent terminals such as TTAs, etc.). The /PERMANENT qualifier should be used with EXTREME CAUTION with logging on direct-connect terminal such as TTA's, TXA's or OPA's since with these terminals the log file will just continue to grow and can't be turned off without rebooting the system. /PERMANENT is mainly intended for security use on such things as dial-up lines, where a log file of the terminal output is desired and the system manager doesn't want the user to be able to stop the logging by doing a NOTRACK command. /REOPEN $ KCAP/TRACK /[NO]REOPEN Used to specify that new versions of a terminal-logging file should [not] be periodically opened. Example: $ KCAP/TRACK/REOPEN /REOPEN re-opens a new version of the log file whenever it reaches a certain number of disk blocks, or whenever a certain time of day or span of time has elapsed, providing at least a certain minimum number of blocks have been written to the file. The maximum and minimum blocks and the time of day and time span are specified using the /MAX_REOPEN, /MIN_REOPEN, /SPAN and /TIME_OF_DAY qualifiers, or by defaults for these which are specified in logical names. The default /REOPEN value is taken from the logical KCAP$REOPEN. /NOREOPEN is used on the command line to override a default /REOPEN value. /SPAN $ KCAP/TRACK/REOPEN /SPAN = minutes /NOSPAN Specifies the approximate time period which should elapse before a new version of a terminal-logging file should be started, when /REOPEN is in effect. Use /NOSPAN to specify that any default /SPAN value should be ignored. The default value for this qualifier is taken from the logical name KCAP$SPAN. Example: $ KCAP/TRACK/REOPEN/SPAN=10 The number of minutes can contain a decimal point. The minimum acceptable value is 1 minute. For more information, see the KeyCapture Commands TRACK Subtopic: /REOPEN /TIME_OF_DAY $ KCAP/TRACK/REOPEN /TIME_OF_DAY = hh:mm /NOTIME_OF_DAY Specifies the approximate time of day when a new version of a log file should be started (when /REOPEN is in effect). Use /NOTIME_OF_DAY to specify that any default /TIME_OF_DAY value should be ignored. The default value for this qualifier is taken from the logical name KCAP$TIME_OF_DAY. Example: $ KCAP/TRACK/REOPEN/TIME_OF_DAY=23:59 The above command specifies that a new log file version should be created at 1 minute before midnight each day. Valid values for /TIME_OF_DAY are 00:00 through 23:59. Note that all 5 characters of the hh:mm syntax are required in all cases. Midnight would be specfied as 00:00. (The special value /TIME_OF_DAY=-1 is the equivalent of /NOTIME_OF_DAY and causes the qualifier to be ignored.) Examples: The log file will be reopened at: /TIME_OF_DAY=00:00 12:00 AM /TIME_OF_DAY=00:01 12:01 AM /TIME_OF_DAY=01:00 1:00 AM /TIME_OF_DAY=12:00 12:00 PM /TIME_OF_DAY=14:03 2:03 PM Any /MIN_REOPEN value is ignored when reopening a file at the /TIME_OF_DAY specified. For more information, see the KCAP Commands TRACK Subtopic: /REOPEN 3 SHOW $ KCAP /SHOW [ALL] (default) KCAP> SHOW [ALL] (default) $ KCAP /SHOW CLUSTER KCAP> SHOW CLUSTER $ KCAP /SHOW IMAGES KCAP> SHOW IMAGES $ KCAP /SHOW LICENSE KCAP> SHOW LICENSE ! $ KCAP /SHOW USERS KCAP> SHOW USERS $ KCAP /SHOW VERSION KCAP> SHOW VERSION Displays KeyCapture-related information. 4 ALL $ KCAP /SHOW [ALL] (default) KCAP> SHOW [ALL] (default) Displays KeyCapture-related information which includes the version of KeyCapture, licensing information, and special-images information. 4 CLUSTER $ KCAP /SHOW CLUSTER KCAP> SHOW CLUSTER Displays any other nodes in the cluster which have started KeyCapture or PEEK & SPY. 4 IMAGES $ KCAP /SHOW IMAGES KCAP> SHOW IMAGES Displays information on the special images registered with KeyCapture. 4 LICENSE $ KCAP /SHOW LICENSE KCAP> SHOW LICENSE Displays license information. 4 VERSION $ KCAP /SHOW VERSION KCAP> SHOW VERSION Display the version of KeyCapture which is currently running. 3 SHUTDOWN $ KCAP /SHUTDOWN KCAP> SHUTDOWN This subcommand is normally only issued from KCAP_SHUTDOWN.COM. The subcommand handles part of shutting down KeyCapture on the system, but does not completely shut KeyCapture down. Therefore, KCAP/SHUTDOWN should only normally be done by KCAP_SHUTDOWN.COM. Doing a KCAP/SHUTDOWN without doing the rest of KCAP_SHUTDOWN.COM can leave KeyCapture in an inoperable state. 3 SPAWN KCAP> SPAWN This command can be used from the KCAP> prompt to spawn a subprocess. The optional parameter is a command string to be executed by the spawned subprocess. The SPAWN command also takes the following qualifiers: /CARRIAGE_CONTROL - Controls subprocess prompt string format. /CLI - To specify a command line interpreter other than DCL. /INPUT - Where the subprocess gets its input commands. /KEYPAD - Whether DEFINE/KEY settings are inherited. /LOG - Display process name when re-attaching to process. /LOGICAL_NAMES - Whether logical names are inherited. /NOTIFY - If a message is received when subprocess finishes. /OUTPUT - Where subprocess sends its output. /PROCESS - Name of the subprocess to be created. /PROMPT - The prompt string to use for subprocess. /SYMBOLS - Whether symbol definitions are inherited. /WAIT - Does parent wait for subprocess (default=yes). For further details, use VMS's HELP on SPAWN, or see the description of LIB$SPAWN in the VAX/VMS Run-Time Library Routines Reference Manual. Examples: KCAP> SPAWN SHOW TIME 20-FEB-1992 17:13:04 %KCAP-I-RETURNED, control returned to process D_STROM KCAP> SPAWN $ SHOW TIME 20-FEB-1992 17:13:19 $ LOG Process D_STROM_1 logged out at 20-FEB-1992 17:13:21.54 %KCAP-I-RETURNED, control returned to process D_STROM KCAP> KCAP> SPAWN/NOWAIT/INPUT=MGR$:CHECK.COM/OUTPUT=MGR$:CHECK.LOG %KCAP-I-SPAWNED, process D_STROM_1 spawned KCAP> 3 /COMMAND_MODE Command mode allows subcommands to be issued as verbs instead of as command qualifiers. As shipped, command mode is the default mode used during KeyCapture interactive command prompting, and non-command mode is used for single-line DCL KeyCapture commands. As shipped: In single-line DCL commands, subcommands are qualifiers: $ KCAP /TRACK ! Start KeyCapture for the current terminal. $ KCAP /SHOW VERSION ! Show the version of KeyCapture. During interactive command-prompting, subcommands are verbs: $ KCAP ! Enter command-prompting mode. KCAP> TRACK ! Start KeyCapture for the current terminal. KCAP> SHOW VERSION ! Show version of KeyCapture. KCAP> SPAWN ! Spawn a subprocess. The subcommands which are accepted as verbs in command mode are: ATTACH, EXIT, FORMAT, HELP, LICENSE, NODE_NAME_CHANGE, NOTRACK, QUIT, SHOW, SHUTDOWN, SPAWN and TRACK. The qualifier form of all the above subcommands is also still accepted when in command mode, e.g. "KCAP> /TRACK" is accepted. 4 Disabling_Command_Mode If desired, you can disable command mode, so subcommands must always be entered as command qualifiers, even during interactive command prompting. To disable command mode during KeyCapture command prompting, define the logical name WATCHER$COMMAND_MODE_PROMPT as False. This logical name can be defined system-wide by KCAP_DEFAULTS.COM, or it can be locally defined in any of the logical-name tables specified by LNM$KCAP_TABLE_SEARCH_LIST, which is defined by KCAP_DEFAULTS.COM. When WATCHER$COMMAND_MODE_PROMPT is FALSE, subcommands must always be entered as command qualifiers, even during command prompting. Example: $ KCAP KCAP> /TRACK ! Not KCAP> TRACK KCAP> /SHOW ! Not KCAP> SHOW 4 Forcing_Command_Mode The /COMMAND_MODE qualifier can be used to force command-mode. After entering the /COMMAND_MODE qualifier, you will not need to use a slash on the command line, but can enter the various subcommands as verbs. You can force command-mode syntax, even for single-line DCL KeyCapture commands by changing the KeyCapture foreign command definitions to include the /COMMAND_MODE qualifier. Change the DCL definitions of the KCAP symbol from: (The _Vx should be replaced with _V5 or _V6 or _V7.) $ KCAP :== $ KCAP$LOCATION:KCAP_Vx to $ KCAP :== $ KCAP$LOCATION:KCAP_Vx/COMMNAD_MODE Once the KCAP symbol is so defined, KeyCapture subcommands may be used as verbs in single-line DCL commands. Example: $ KCAP TRACK ! Instead of $ KCAP /TRACK. $ KCAP SHOW ! Instead of $ KCAP /SHOW. 2 Overview KeyCapture tracks terminal input, logging it to a file. KeyCapture logging is usually started by inserting an @KCAP$LOCATION:KCAP_LOGIN command into the LOGIN.COM or SYSLOGIN.COM file for the user whose input is going to be tracked. KeyCapture log files are recorded in a binary format. They can be converted to a more readable format via the stand-alone KCVT.EXE program. KeyCapture have been designed to have the following features: + KeyCapture may be run from a terminal which is connected directly to the computer, or through a terminal server, or from a DECwindows DECterm window, or from a DECnet "remote terminal" as created by SET HOST. + A variety of other features allow users and system managers to configure KCAP's options to their liking. 2 Defaults Many of the KeyCapture command qualifiers may have default values supplied for them via logical names. These logical-name default values are usually defined system-wide by the KCAP_DEFAULTS.COM file. It is also possible to customize these logical-name default values in ones own logical name tables. KCAP_DEFAULTS.COM defines the logical name table search list LNM$KCAP_TABLE_SEARCH_LIST. This table search list specifies the tables which are searched for logical-name default values. These tables are searched in the order specified by this logical name. As shipped, KCAP_DEFAULTS.COM defines LNM$KCAP_TABLE_SEARCH_LIST to search the LNM$PROCESS, LNM$JOB and LNM$GROUP logical name tables, in that order, before checking for a system-wide default value in the table LNM$KCAP_DEFAULT. See the KCAP_DEFAULTS.COM file for more information. 2 Security Any user being KeyCapture-logged must have been authorized by the system manager for KeyCapture logging since sensitive, non-echoed input data might be logged. Rights-list Identifiers are used to specify who may be logged with KeyCapture. The Rights-list Identifier used is KCAP$INPUT_LOGGER. To use KCAP/TRACK, the user must hold the Rights-list Identifier KCAP$INPUT_LOGGER. KeyCapture 5.1.14 suppresses logging of passwords entered with the DCL SET PASSWORD command, and for SET HOST, SET HOST/LAT, SET HOST/TELNET, SET HOST/DTE, and SET HOST/RLOGIN. It also suppresses logging of passwords for LOGINOUT.EXE and VMS's TCPIP FTP and TELNET commands. The programs pointed to by the VMS logicals OPENVMS$FTP, OPENVMS$RLOGIN and OPENVMS$TELNET are now included in the list of standard programs   which do not log non-echoed input. The 5.1.14 release of KeyCapture also allows the system manager to add additional programs to the above list of programs for which passwords aren't logged. See the section in KCAP_DEFAULTS.COM concerning Special Images. PLEASE NOTE: KeyCapture will record passwords and other non-echoed input for programs other than the above. USE WITH CAUTION on any sensitive accounts or systems if you have programs other than the above which are password protected. When logging-in to another system with any of the SET HOST commands (including TELNET), KeyCapture does not log any characters which are input to the remote system. KeyCapture does log the fact that input was entered, but the characters themselves aren't logged. Since the input is going to another system, this doesn't compromise the security of the system on which KeyCapture is running. If the remote system is running VMS, KeyCapture can be used on that system to log the input without jeapordizing password security for the remote system. To protect passwords, input keystrokes are also suppressed for the MS_SERVER process which is used as part of NDC's MultiSessions product on ALPHA systems. This makes the /NOBACKGROUND and /NOSINGLE_WINDOW and /NOWINDOW commands obsolete for KeyCapture. (These commands remain valid for NDC's Peek & Spy product.) KeyCapture does record the input for each individual MultiSessions session. GREAT CARE SHOULD BE USED WHEN GRANTING USERS THE KEYCAPTURE RIGHTS-ID, SINCE THIS ALLOWS LOGGING OF NON-ECHOED INPUT. Precautions are taken in KeyCapture to avoid logging VMS passwords BUT PARTICULARLY FOR THIRD-PARTY SOFTWARE, THERE IS THE POSSIBILITY THAT NON-ECHOED INPUT LOGGED BY KeyCapture COULD CONTAIN PASSWORDS. 3 Rights-IDs KeyCapture logging is authorized for specific users by granting them the proper rights-ids. For KCAP/TRACK/ the rights ID is KCAP$INPUT_LOGGER. To add these identifiers to the system rights database use the AUTHORIZE commands ADD/IDENTIFIER KCAP$INPUT_LOGGER. To then grant these identifiers to specific users, use an AUTHORIZE command in the form of GRANT /IDENTIFIER KCAP$INPUT_LOGGER J_JONES A program and command file are provided in the KeyCapture distribution to help the system manager set up the KCAP$INPUT_LOGGER rights-id on the system. See KCAP$LOCATION:KCAP_GRANT_ID.COM for details. GREAT CARE SHOULD BE USED WHEN GRANTING USERS THE KEYCAPTURE RIGHTS-ID, SINCE THIS ALLOWS LOGGING OF NON-ECHOED INPUT. FOR THIRD-PARTY SOFTWARE, IT IS POSSIBLE THAT THIS NON-ECHOED INPUT COULD CONTAIN PASSWORDS. 2 Version This help is for version 5.5.17 of KeyCapture(tm). PROPRIETARY RIGHTS NOTICE: All rights reserved. This material contains the valuable properties and trade secrets of Networking Dynamics Corp. of Clearwater, Florida, United States of America (NDC), embodying substantial creative effort and confidential information, ideas and expressions, no part of which may be reproduced or transmitted in any form or by any means, electronic, mechanical, or otherwise, including photocopying and recording or in connection with any information storage or retrieval system without permission in writing from NDC. The information in this document is subject to change without notice and should not be construed as a commitment by NDC. NDC assumes no responsibility for any errors that may appear in this document. COPYRIGHT NOTICE: Copyright (c) 1983, 1987-2016, an unpublished work by Networking Dynamics Corporation. All rights reserved. PEEK & SPY, MultiSessions, and KeyCapture are trademarks of Networking Dynamics Corporation. Alpha, VAX and VMS are registered trademarks of Hewlett-Packard Company. 2 Callable_Interface The KCAP_Vx.EXE program as distributed with this version is a very simple program which just gets the command line with a call to LIB$GET_FOREIGN and then passes it to KCAPSHR, a sharable runtime library. You may use this interface to integrate KeyCapture into your own applications, making KeyCapture a part of your product. By specifying the facility name parameter, you may customize the error messages to use your product name as a prefix. 3 KCAPSHR KCAPSHR is a callable entry point in a protected shared image which allows you to call KeyCapture as a subroutine, from your own programs and menus. Note that KCAP_Vx.EXE calls this KCAPSHR passing it the command line which was entered as a DCL foreign command. Format: CALLS #5,G^KCAPSHR kcapcmd ,actrtn ,facnam ,actprm ,outlen Arguments: kcapcmd VMS usage: char_string type: character string access: read only mechanism: by descriptor--fixed length string descriptor Character string containing the KeyCapture command to be executed. The kcapcmd argument is the address of a descriptor specifying the command string being passed to KCAPSHR. It must begin with the verb KCAP. The syntax rules for this command string are the same as for any command which KeyCapture would process from the DCL command prompt. kcapcmd may not be passed as zero but the length in the descriptor of the command may be 0 which will cause KCAPSHR to prompt for a command interactively. actrtn CALLING OF THE USER'S ACTRTN IS NOT YET IMPLEMENTED FOR VERSION 4 on AXP. VMS usage: procedure type: procedure entry mask access: call without stack unwinding mechanism: by reference User-supplied action routine to be executed during message processing. The actrtn argument is the address of the entry mask of this routine. If an actrtn is specified and the actrtn returns a success status (the low bit of R0 is set) then the message is output using $PUTMSG. If the actrtn returns a failure status, (the low bit of R0 clear) then no message is output. If specified as 0 then no actrtn is called and the messages are output by $PUTMSG. facnam VMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor--fixed length string descriptor Facility prefix to be used in the first or only message written by $PUTMSG. The facnam argument is the address of a character string descriptor pointing to this facility prefix. If passed as 0 then KCAP is used as the facility name. actprm CALLING OF THE USER'S ACTRTN IS NOT YET IMPLEMENTED FOR VERSION 4 on AXP. VMS usage: user_arg type: longword (unsigned) access: read only mechanism: by value Parameter to be passed to the action routine. The actprm is a longword value containing this parameter. If there is no parameter to pass then actprm should be specified as 0. outlen VMS usage: word_unsigned type: word (unsigned) access: write only mechanism: by reference The number of bytes in the command passed to KCAPSHR is returned here unless the command passed was only "KCAP/COMMAND" in which case outlen is returned as zero indicating that there was no actual command passed and that a command was prompted for interactively and executed. This is useful for determining whether or not to call KCAPSHR again in prompting mode. This argument must be passed as the address of a word in the calling program for which there is write access.