Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / dos / cmdline / clp / clp.doc < prev next >

Wrap

Text File | 1989-10-14 | 20.9 KB | 577 lines

CLP - A 'C' Command Line Processor, Version 1.1 ------------------------------------------------- ***************************************************************** * * * This archived software set is shareware! It is NOT public- * * domain, and though it is free of charge it may only be * * distributed with the following conditions: * * * * 1. The full archive CLP_V11.ARC is distributed without * * modification. * * 2. No commercial gain is directly sought from any of * * the files contained within the archive without the * * author's prior approval. * * 3. Notification should be sent to the Author (name & * * address & e-Mail address below) of any use of CLP * * in programs outside the individual's personal use. * * This includes public-domain and shareware software * * as well as commercial software. * * * * Users requiring versions of CLP for different memory models * * should send a postage paid reply envelope to the address * * below. Registering may also be accomplished by sending a * * diskette (360K, 1.2M, 740K, 1.44M) to the address below. In * * reply, you will receive the latest version of CLP for all * * memory models, the complete CLPLIB utility and instructions * * for linking CLP definitions into code directly without the * * need for a library. * * * * Please ensure that the reply envelope has enough postage to * * cover costs. Instead of postage, you may send a 1.44M * * diskette! Gets around the international stamp system! * * * *- - - - - - - - - - - - - - - - - - - - - * * * * Queries, comments, suggestions & registration to: * * * * Karl Keyte, e-Mail: ESC1332@ESOC.BITNET * * E.S.O.C., Phone : +(49) 6151 886783 * * Robert-Bosch Strasse 5, * * 6100 Darmstadt * * West Germany Date : September 1989 * * * ***************************************************************** 1 Introduction ------------ CLP is a general purpose command line processor for the 'C' language. Looking at the sources for various programs written in 'C' it is clear that a lot of work has been repeated in handling command line options and parameters. CLP provides a means by which the general format of the command line may be defined in a Command Line Definition file (.CLD), and processed by a single interface call. Following that call, values and settings of parameters and switches may be queried by additional calls. The idea and much of the flavour of CLP comes from the VAX/VMS operating system, where command definitions may be build up in a very similar fashion. CLP has been tested with Turbo-C (2.0) and Microsoft C (5.1). The '#include' file given conforms to ANSI standards, and should therefore be accepted by any ANSI compiler. The object module uses a standard 'C' parameter stack. A compiler is provided which takes the Command Line Definition file and generates a Command Line Library (.CLL) file which contains definitions for ALL utilities using the CLP interface. The .CLD file should be maintained by adding and deleting utilities from it as required. Running the compiler will generate the full Library file (.CLL) from the definitions. Four functions are available to the caller. 'clp_accept' initialises the CLP processor for a given program and command line. 'clp_get_spec' returns the specification code for a particular parameter or switch option. 'clp_get_value' returns the value associated with a parameter or switch option if present. These are described in detail in the following sections. When parameter and switch processing has been completed, the user may recover certain portions of system memory by calling the procedure 'clp_release'. 2 Interface Calls --------------- 2.1 clp_accept ---------- Function: Initialise CLP for specified program and command line. Syntax: #include "clp.h" void clp_accept ( char *function, int argc, char argv** ); Prototype: clp.h Remarks: Sets up the data structures in preparation for other interface calls. 'function' specifies the program name, as given in the CLD file. 'argc' and 'argv' are the command line parameters of the main program, and should be passed to 'clp_accept' exactly as they were received. If the command specified does not conform to the definition in the CLD, the program will exit with the exit status of 1. 'clp_accept' attempts to open the CLL library file by checking first the environment variable CLPLIB. If this is defined, the file given will be used. If the environment variable is undefined, 'clp_accept' attempts to locate the file CLP.CLL in the current searchpath. If it is not found, the program will exit with an exit code of 1. Return Value: None. 2.2 clp_get_spec ------------ Function: Returns the specification code for a specified parameter or switch option. Syntax: #include "clp.h" int clp_get_spec ( char *name ); Remarks: Finds the specification associated with the switch or parameter 'name'. The name must be present in the CLD file. Return Value: The return is one of the following: CLP_ERROR Not found, i.e. was not defined in the CLD file. CLP_NOTSPECIFIED Not specified in the command line. CLP_DEFAULTED Not specified in the command line but is on by default. CLP_SPECIFIED Explicitly specified in command line. CLP_VALUEDEFAULTED Contains a value which has been defaulted. CLP_VALUESPECIFIED Contains a value which has been explicitly specified. CLP_NEGATED Explicitly negated. 2.3 clp_get_value ------------- Function: Returns the value associated with a parameter or value switch option. Syntax: #include "clp.h" char *clp_get_value ( char *name ); Remarks: Finds the value asociated with the specified parameter or switch option, 'name'. The name must be present in the CLD file. Return Value: Returns a pointer to the value string. The string is static, and must be copied by the user if it is to be further used. NULL is returned if no value is defined, or if the 'name' specifies an invalid parameter or switch name. 2.4 clp_release ----------- Function: Releases all memory reserved by the CLP processor. Syntax: #include "clp.h" void clp_release ( void ); Remarks: All memory and associated data structures for use with CLP are released. No call to 'clp_get_value' or 'clp_get_spec' should be attempted (they will return NULL and CLP_ERROR respectively) before an intervening call to 'clp_accept'. Return Value: None. 3 CLD File Format --------------- The definitions for all programs using CLP must exist in a library. This library, type .CLL, is formed from a source definition file, CLD. It is the CLD which must be changed when a command line format is changed or when new programs using CLP are added. This section describes the syntax of the source file, CLD. The CLD file generally comprises definitions, each of three sections: a program name definition; one or more parameter specifications; one or more switch specifications. These are covered in the respective order: 3.1 Program Name Specifier ---------------------- :<program_name> This key is used to introduce the name of a new program for use with the CLP system. The name must be a valid MS-DOS program name, i.e. 1-8 alpha-numeric characters. These clauses are used to separate program command line definitions, a definition being considered complete either when the end of file is reached, or when the next ':<program_name>' clause is encountered. 3.2 Parameter Specifier ------------------- $<par_name>[[;DEFAULT="<def_val>"]|[;REQUIRED [;PROMPT="<prmt>"]] <par_name> is a parameter specifier. The names are not flexible. The first must be P1, the second, P2, etc. <def_val> identifies a default value to be given to the parameter is it is not specified on the command line. If DEFAULT is specified, the REQUIRED and PROMPT keywords have no meaning, and an error will be generated when the CLD is converted to the CLL. The default value may contain up to 80 characters. <prmt> is a string which will be used to prompt the user for a required parameter. For this reason, the PROMPT keyword only has a useful context following the REQUIRED keyword, and an error will be generated if this is not the case. <prmt> may be a maximum of 50 characters. If a parameter is REQUIRED, but has no PROMPT specified, the name of the parameter (e.g. P1) will be used for the prompt. 3.3 Switch Option Specifier ----------------------- /<sw_name> [;NEGATABLE] [;DEFAULT] [;VALUE] [ ; REQUIRED | DEFAULT="<def_val>" ] <sw_name> may be up to 15 characters. NEGATABLE allows the option to be explicitly negated with the /NO<sw_name> form. A switch value may not be specified as both negated and containing a value. DEFAULT set the option on be default. It is meaningless (but valid) to specify DEFAULT without NEGATABLE, since the switch would be permanently set on. VALUE allows the switch to take a value which is optional, unless the REQUIRED keyword follows VALUE. If DEFAULT=<def_val> follows the VALUE keyword, the switch will take the default value if one is not specified. The <def_val> default value may be up to 80 characters. If a NEGATABLE switch is negated and has a default value specified in the definition, the value will be discarded by the negation, and will be set to NULL. DEFAULT and DEFAULT="<def_value>" are mutually exclusive. 3.4 Example ------- The following example serves to demonstrate the use of CLP. Imagine a delete facility which allows the user to move the 'deleted' file to another directory rather than removing it completely. Clearly, one parameter is essential; the file specification. The directory for deleted files may be specified by a value switch. We can introduce two further facilities. The first, an option LOG to allow us to have a detailed display of the success or failure of the deletion, and secondly, SAFETY, to allow the delete to be aborted if the file already exists in the backup directory. If we call the facility XDEL, the .CLD definition (XDEL.CLD) would look similar to this: !============================================================== ! ! XDEL Command-Line Definition ! ! Note how comments may be inserted, as well as blank lines! ! !============================================================== :xdel ! Function Name $p1; required; prompt="Filespec" ! Parameter required /backupdir; negatable; value; default="C:\DELETED" ! Del. dir /log ! Display status info. /safety; negatable; default ! Ask before overwriting !============================================================== The file may then be compiled: C:\> clplib xdel which would generate XDEL.CLL Note that the /OUTPUT option for CLPLIB changes the default library name, e.g. C:\> clplib/outp=mylib xdel would generate the output in a file called MYLIB.CLL. The /VERBOSE option displays the CLD source with line-numbers as it is being compiled. 4 CLL File Format --------------- The compiler provided with the CLP package is used to convert the .CLD source definition file to a .CLL library definition. The format and syntax of the source has been described above. The purpose of this section is to describe the internal format of the library file. This format is subject to change between versions of CLP, and this document should be used as the prime source of the library structure. The CLP version 1.1 library file has the following format: Offset | Size | Data Type | Description ---------+--------+-------------+-------------------------------- 0 | 71 | String | Copyright message. This | | | message may not be changed or | | | 'clp_accept' will fail. ---------+--------+-------------+-------------------------------- 71 | 9 | ZString | Title of function (Program) ---------+--------+-------------+-------------------------------- 80 | 2 | Integer | Number of parameters/switches | | | belonging to function. ---------+--------+-------------+-------------------------------- 82 | 2 | Bytes | Unused, reserved. ---------+--------+-------------+-------------------------------- 84 | 2 | Bitmap | Bit mapped fields comprising: | | | Bit 0 : Negation permitted | | | flag. 1=Negation | | | permitted. | | | 1-2 : Value mode flag. | | | 00=No value | | | allowed. 01=Value | | | optional. 02=Value | | | required. 03=N/A. | | | 3 : Parameter required | | | flag. 1=Parameter | | | required, else is | | | optional. Not used | | | used for switches. | | | 4 : Type flag. 0= | | | parameter, 1=Swtch | | | 5-6 : Default mode. | | | 00=not defaulted, | | | 01=defaulted, | | | 02=default value. | | | 03=undefined. ---------+--------+-------------+-------------------------------- 86 | 16 | ZString | Name of the switch or param. ---------+--------+-------------+-------------------------------- 102 | 51 | ZString | Prompt string for required | | | parameters. ---------+--------+-------------+-------------------------------- 153 | 81 | ZString | Default value for parameters & | | | switches with an associated | | | default value. ---------+--------+-------------+-------------------------------- 334 | 150 | Structure | Copy of above fields from | | | offset 84 onwards. One per | | | additional parameter or switch ---------+--------+-------------+-------------------------------- ??? | ??? | Structure | Complete copies of above from | | | offset 71 onwards. One per | | | additional function. ----------------------------------------------------------------- The ordering of the switches and parameters in the .CLL file is according to the order they appear in the .CLD source definition file. The same applies to the ordering of the functions within the file. 5 Bugs fixed and changes made since version 1.0 --------------------------------------------- The following is a list of corrected bugs and changes made since the last release (Version 1.0, archive CLP_V10.ARC) of the CLP utilities. o When an ambiguous switch was specified, the checks made only applied to the first switch matching, rather than reporting the ambiguity. For example, a switch given as /NOA (where 'A' is actually ambiguous) would report "Switch 'Axxxxx' not negatable", if the first switch starting with 'A' is not actually negatable. The correct response, of course, is that switch 'A' is ambiguous. This has now been corrected. o The copyright message at the header of the library file (.CLL) must remain intact, or the call to 'clp_accept' will fail with an 'Invalid Library Format' error. o The numbering of the command line parameters used internally had an error in version 1.0 which caused command lines with not all parameters specified to be rejected. This numbering has been corrected, and command lines may now contain any mixture of parameters, provided that the value '-' is given for a parameter which is not to be specified. 6 Run-time Error Messages ----------------------- This section covers the possible run-time error messages. All are fatal and processing will abort should one of the errors be encountered. ?CLP01: Invalid function name for 'clp_accept' The function name passed as a parameter to 'clp_accept' has either 0 or >8 characters and is therefore invalid. ?CLP02: CLP file 'CLP.CLL' not found in search path No CLPLIB environment variable was set to point to the CLP library, causing 'clp_accept' to look for CLP.CLL in the search path. This file was not found. ?CLP03: CLP file 'XXXXXX' not found The CLPLIB environment variable points to a file which does not exist or cannot be opened. ?CLP04: Function 'XXXXXX' not found in CLP library The function name passed to 'clp_accept' was not found in the CLP library being used. ?CLP05: CLP library 'XXXXXX' has invalid format Either the library is corrupt or the copyright message header in the library has been changed. ?CLP06: Insufficient memory to process command line parameters Available memory was exhausted when trying to allocate memory for parameter/switch data structures, default/prompt strings or the user's input string for a required parameter. ?CLP07: Ambiguous switch, 'XXXXXX' More than one switch exists with the same specified starting character sequence. Specify switch more fully. ?CLP08: Illegal switch, 'XXXXXX' The switch specified is not valid according to the CLP library specification. ?CLP09: Switch 'XXXXXX' is negated and has value A switch was specified negated with associated value. This is not permitted. ?CLP10: Value not allowed for switch 'XXXXXX' The specified switch may not take a value. ?CLP11: Switch 'XXXXXX' may not be negated The specified switch may not appear in the negated form. ?CLP12: Value is required for switch 'XXXXXX' Specifying the switch without an associated value is not permitted. Include a value. ?CLP13: Insufficient memory to process switch options Available memory was exhausted when trying to allocate memory for the user's switch values. ?CLP14: Invalid parameter, 'XXXXXX' A parameter was given which was not expected. Examine the syntax of the command as too many parameters were specified. ?CLP15: Invalid switch, 'NO' A switch 'NO' was specified, implying the negation of a null switch. This is not permitted.