Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Poster s 351 Build ing a SAS® Front-end using the Command Definition Utility Hallett German GTE Laboratories, Inc. Introdu ction Unll<e MVS, the SAS® system does not provide a front-end that VMS users can easily customize. The result has been many VMS sites writing lengthy command procedures using DCL (Digital Command Language.) These are far from intuitive and are difficult to support. A more powerful alternative is using the Command Definition Utility (CDU) to create your own DCL SAS verb. [SAS's version of this can be found in SAS$ROOT:[SAS606.1MAGE]SAS606.CLD However, the documentation to do this is in several DEC manuals and examples (especially with C) are sparse. This paper attempts to demystify this process by creating a simplified annotated DCL verb. References for further information are provided. Once you understand the framework and have an example to work from, you can then build your own DCL front-end repeat steps 1·5 again (and as many times as necessary.) Figure 2 shows a general command procedure (.COM file) that allows you to run steps 1·5 by just entering one command. Just enter RUNIT program at the DCL ($) prompt. (With program the name of your C program and command.) This results in program being assigned to the P1 symbol. (I use the /LIST and /SHOW qualifiers to assist in the inevitable debugging of the C program. These produce a program listing of program.lis that contains intermediate macro expansions.) Figure 1 : Process to create a DCL command. Create a .CLD fila. Figure 1 shows the overall process: STEP 1 Creatjng a Commoand Lanouage DefjnjtiOn file 1CLPl. This is the "skeleton and skin" of a DCL verb. CLD files define the command-to-be by specifying all valid qualifiers, parameters, default values, and the like. · STEP 2 Create and Compile a C prpgrarn This is the "muscle and nerves" of the DCL verb by specifying the sequences enacted when a certain qualifier or parameter is specified. An object file is produced; STEP 3 Link the c Program The C Object file is linked resulting in an executable. Other object files may be linked as well. STEP 4 Add the QCL yerb to the process command table /the detaylt) Placing it in your LOGIN.COM means the DCL verb will be available to you each time that you log on. If you wish to share a command with other users, then ask your VMS system administrators to add it to the permanent system command table. STEP 5 Ryn the new DCL ooromand The command should be now successfully created and available to you. Enter the command name and the specified processing should be performed. If not, Craata a C oroaram (.cl • CC program.c tha C oroaram Com~lla , LINK program Link tha ob/Kt fl» ' SET COMMAND program.CLD Place comand Into command llllhl• ' Invoke varb and parameter NESUG '91 Procee dings 352 Posters SYNONYM Figure 2: Example of a generalized batch file to create DCL verbs RUNIT.COM $ cc 'P1'.c/listlshow•(intarmediate) $link 'P1 $ set command 'P1'.cld $'P1 The remainder of the paper discusses in greater detail the components used to create a new DCLverb. The .CLD file The .CLD is a text file that sets the boundaries of a verb. The basic syntax is fairly simple. Figure 3 lists the skeleton of a valid .CLD file: Figure 3 Skeleton of a .CLD file DEFINE VERB verb_name IMAGE directory.1ile PARAMETER p1, PROMPT= "prompt text", LABEL-label, VALUE(REQUIRED,LIST) PARAMETER p2,PROMPT="prompt texr, LABEL· label, VALUE(DEFAULT="value") QUALIFIER value VALUE(REQUIRED) SYNONYM "synonym' Elements of .CLD file DEFINE Specifies verb to be defined. IMAGE Specifies the executable to invoke to process the DCL verb. PARAMETER Defines the positional parameter (P1·P8) associated with the parameter. (Parameters are not entered with a/.) You can also specify for the parameter the following: a prompt, a label, if the parameter is required or has a default value. QUALIFIER Specifies a qualifier is to be used. (Qualifiers are specified. You can also specify for the parameter the following: a prompt, a label, if the parameter is required or has a default value. NESUG '91 Proceedings Creates an alias(es) for a VERB. To help clarify this, a simple example is provided. Let us create a new DCL verb called NAME that wiU use all of the above. (This example will be used to discuss the other CDU elements as well.) Figure 4 lists the .CLD file used to create this verb. Figure 4 NAME.CLD VERB name IMAGE disk1 :(hhg1.c]name.exe PARAMETER p1, Prompt • "Your First Narne", LABEL=first, VALUE(REQUIRED) PARAMETER p2, Prompt • "Your Last Narne", LABEL= last, VALUE(Default="Smith") QUALIFIER middl~value What is going on here is quite simple: • A new verb narne Is being created. It uses the executable name.exe (in this case a compiled C program) to process the verb. • Two parameters (no slash is needed) are allowed for the NAME verb. The first parameter is required and is associated with the label (symbol) first in the C program. (You will be reprompted until entering a value.) It uses the prompt "Your First name. "The second parameter is optional and is associated with the label (symbol) last in the C program. It uses the prompt "Your Last name. • Hused and no value is - specified, then the default value of SMITH is used. Note that either of these can be entered on the command line if you do not want to be prompted. (Such as NAME HAL GERMAN.) • A qualifier is available (!MIDDLE). • Thus the following are possible sessions using the NAME verb: NAME Your First Name: PROC -Your Last Narne: REPORT F: PROC L:REPORT NAME Your First Name: PROC -Your Last Name: F: PROC L:SMITH NAME /MIDDLE..THE MACK KNIFE F: MACK M: THE L:KNIFE Poste rs Space does not permit a discussion of other components of the .CLD file such as DEFINE SYNTAX (Use to modify an already defined verb), and DEFINE TYPE (Define values for syntax, values, labels, etc). Keep the following in mind when creating a .CLD to be used as a SAS front-end: 1. Use DEFINE TYPE to build a category of related keywords. Then you can place a type.. statement in a value adjective: define type names keyword .... (later on) !Qualifier name value ... rtvoe.. names.reQuiredl 2. Use the built variables to define values. These include $DATETIME (allows date and time values), ·$FILE(checks if a valid file name), $NUMBER(checks if is a valid number), $QUOTEDSTRING (checks if string is in quotes [and retains quotes.]) (PARAMETER p2, VALUE{TYPE=$NUMBER) 3. Use the DISALLOW clause to specify corminations of parameters or qualifiers not allowed. Idisallow P1 and 01 4. Give the user more flexibility by use the NEGETABLE adjective as part of the qualifier or parameter. This allows users to enter a "NO" prefix to a qualifier name. Iqualifier mess negatable. The tun part - the C program. Even if you are knowledgeable in C, creating a C program to process the result from a .CLD file can be a frightening experience. Two components particularly can cause this anxiety - 1) use of string descriptors, and 2) CLI run time procedures. Each will be briefly discussed. String Descriptors Strings in VAX C are represented by string descriptOrs which are really data structures containing the address type, length, and class of the string. The problem is that VMS C has no direct way to pass by descriptor. Instead, you have to face the 353 ugly and unnerving task of building your own string descriptors. The clearest explanation on this topic can be found in1he May 1990 Issue of DEC Professional (pages 132-140) CLI Run Time Procedures There are 4 major CLI (Command Language Interface) routines. We will only be discussing two of them: CU$pR ESENT louali08 0 Betums if a qualifier is present. This will always be true if the qualifier is the default. (Unless a negatable version of a qualifier is used such as INONUKES.) Results are placed in the variables CLI$PRESENT or CLI$NEGATED. CL!$GEDfALUEijnput strjng output strina tenath of stem This values processes a string and returns an output string. Results are placed in the SS$NORMAL variable. We are now ready to look at the NAME.C program. #include descriprThe header of descriptors and types'/ #include stdio !"The header to use printf*/ #include ssdef rThe header to use SSSNORMAL*/ main() { register status; rstatus is heavily used so place in a rregister*/ char fname(25],1name[35],mname(1 OJ; r arrays are used to hold names*/ short ret_length.O; rinitialize length variable*/ $DESCRIPTOR(fn_in, "firstj; rlabel In .CLD*/ $DESCRIPTOR(fn_out, fname); $DESCRIPTOR(In_in, "last"); $DESCRIPTOR(In_out, lname); $DESCRIPTOR(mn_in, "middle"); $DESCRIPTOR(mn_out, mname); rDeclare a descriptor for *I reach input and output string*/ first: status-cliSGET_VALUE(&fn_in,&fn_out,&ret_length ); rRead first name*/ If (!status) lib$stop(status); rExit H faifed•t last: status-cliSGET_VALUE(&In_in,&ln_out,&ret_length); rRead last name*/ if (!status) lib$stop(status); rExit H faMed*/ middle: status-cliSGET_VALUE(&mn_in,&mn_out,&ret_length); rRead first name*/ rlf evervthing worked then .. .*/ NESUG '91 Procee dings 354 Posters . rThis does not remove*/ rtrailing blanks*/ if (status"'"' SS$_NORMAL) Waltham. Ma 02254 617-466-2290 hhg1 @bunny .gte.com printf("F:o/os L:o/os",fname,lname); else printf("F:o/os M:o/os l:o/os*, !name, mname, lname); } rEnd of C program*/ SAS ® is a registered trademark of the SAS Institute Note that the label specified in the .CLD file is passed as input via the string descriptor. References [Annotated] Keep the following in mind when building a C program to serve as a SAS-front end: [Since the information on building a DCL Verb in C is not In one place, I have described what each reference contains.] 1. Same people have built their own function calls that perform a lot of the above front-end work. An example is available from the author above request. 2. Take the time to print the DESCRIP header file to better understand the components of string descriptors. 3. Enhance your program by using the error messages to provide smoother error handli~ and easy to understand error messages. !hiS is compiled by entering MESSAGE errortibrary. 4. Create a help document (.hlb) and use the LIBRARIAN command to add to the help library. Help documents are in a text file in a special format. SET COMMAND We've already mentioned about SET command used to create the DCL verb. This section just mentions the qualifiers that you can use with this command. /DELETE /LISTING /OUTPUT /REPLACE /TABLE Deletes a verb Give an output listing Specifies the command table file. Replace a verb. Specifies command table to use. Conclusions This can only be a brief introduction on the major issues in creating a front-end using the Command Definition Utility (CDU). By using the simplified framework, one can have the courage to look ~t ~he various DEC manuals (see below) and start bUilding your own DCL verbs. Getting In touch with me/Trademarks Hallett German GTE Laboratories Inc 40 Sylvan Road NESUG '91 Proceedings VAX VMS, DCL, and DEC are trademarks of the Digital Equipment Corporation. Digital Equipment Corporation Guide to VAX C 19B9 [Describes the .VAX C compiler. Look at pages 1314 through13·18 for some examples on passing by descriptor.) Digital Equipment Corporation VMS Command Definition Utility Manua/1988 (Volume 28 [Describes the .CLD file component~? and SET Command.] Digital Equipment Corporation VMS Librarian Utility Manual1988 (Volume 2B) [Describes the LIBRARIAN command and HELP libraries.] Digital Equipment Corporation VMS Message Utility Manual1988 (Volume 28) [Describes the MESSAGE command and the message source file components.] ·Gibes, Kernon •A VAXNMS Command for SASJBatch Jobs• SUGI14 Proceedings 1989 pp. 1497-1501 [Kemon does a good job describing building your own SAS DCL verb and covers some of the above. His program was written in FORTRAN and has . . provided source in the_past. Also ~e~bes building your own foreign DCL Interlace whiCh 1s not described In this paper.] Jaeschke, Rex •String Descriptors•_Digital Review May 1990. pp. 132·140 [I found the DEC manual on this topic less than friendly. I suggest look at the DESCRIP file and reading thiS article. Rex has a regular COlumn on C, c++. and VMS that 1recommend reading)