Download Building a SAS Front-End using the Command Definition Utility

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)