Getting Started
Getting Started with CobolScript®
Important point
Before you dive headfirst into CobolScript programming, you will need to learn the basics, like how to edit your CobolScript programs, how to run them, and how to debug them. This chapter aims to answer the basic logistical questions of CobolScript coding that you may have, as well as providing a background on CobolScript interactive mode, which contains some useful debugging tools. With the information here, you’ll be ready to learn the CobolScript language.
Just as a note, all of the screens shown in this chapter, with the exceptions of the Windows®-specific information in Figures 2.1 and 2.2, are representative of any CobolScript platform; don’t worry about whether the figure shows an MS-DOS screen or a Unix screen, because the syntax and output of the illustration would be the same no matter what the platform.
Creating and Editing CobolScript Programs
Use a standard text editor to create and edit your CobolScript programs. In Windows®, editors such as Notepad or Wordpad work well. If you use Wordpad, make certain you save your files as text documents, and specify the extension when naming your program, as in Figure 2.1, or Wordpad will save the file with a default extension of .txt. Also, in Wordpad you’ll find it easiest if you choose a fixed-width font for your editing such as Courier New. This will allow you to later open your programs in Notepad, MS-DOS EDIT, or in Unix without a loss of formatting. You will probably find yourself using the aforementioned MS-DOS EDIT text editor (accessible by typing the word edit at the DOS prompt) when debugging, because despite its old-fashioned appearance, it tracks the current column and row positions of the cursor, which can allow you to quickly locate a program line number. Figure 2.2 shows an EDIT screen, with the cursor positioned down and to the right of center; the resulting Line and Column position values appear in the lower right corner of the screen.
If you choose to edit your programs in Unix, any editor that saves documents as plain ASCII text will suffice. Like MS-DOS EDIT, vi is a useful editor because it provides the means to quickly navigate to a particular line number. Teaching vi is beyond the scope of this manual, however, so refer to a Unix or vi-specific reference for more information.
If you are using CobolScript Professional Edition, you will probably find CobolScript CodeBrowser™ to be a useful tool for printing and examining your programs; CodeBrowser™ is discussed in detail in chapter 9.
Running CobolScript from the Command Line
The simplest way to use CobolScript is by running a CobolScript program in command line mode. To do this, type:
cobolscript.exe <program-name>
at the command prompt, where <program-name> is the name of the program you wish to run (don’t literally enclose the program name in < >; we use this syntax to indicate that program-name is an argument to the CobolScript executable, cobolscript.exe). This command assumes that you have already included your CobolScript directory in your PATH environment variable, or alternatively, that you are executing the command from within the CobolScript directory. If you need instructions on how to include your CobolScript directory in your PATH variable, refer to the Installing CobolScript section of Chapter 1, Introduction to CobolScript / Installation Instructions.
If you’re using the Windows® version of CobolScript (rather than a Unix version), running from command line mode means that you are running your CobolScript programs in an MS-DOS session. However, it is important to note that although your CobolScript applications can be run from the DOS prompt, CobolScript is not a DOS application; it is a native 32-bit application that excludes Windows-specific graphical components in order to minimize the CobolScript engine’s footprint and to provide cross-platform capability. Graphical development with CobolScript is achieved through the use of a web server and browser-based applications, discussed in more detail in Chapters 6 and 8. See the section titled Running CobolScript from a Web Server and Browser later in the chapter for more information on getting started in a web-based environment.
Running CobolScript from Windows® command-line mode, you can drop the extensions if you like, and just type:
cobolscript <program-name>
Command line program execution will direct all output to the current command line window, and therefore all output will be plain text. Several of the example programs contained with CobolScript are designed to run in command line mode; figure 2.3 shows the output of the ARITHMETIC.CBL example program in an MS-DOS prompt window.
CobolScript also comes with a number of command line options. If you aren’t already familiar with the term, a command line option is a switch that you set at the time that you call an executable program, which in this case is the CobolScript executable. These switches allow you to change some specifics in the way that CobolScript runs, at the time you run it. If you type cobolscript.exe at the command line prompt, without any program arguments specified, you will see a list of the CobolScript command line options.
Figure 2.4 illustrates this in an MS-DOS window (on other platforms, you would need to specify the .exe extension to the CobolScript executable). The syntax of the CobolScript Standard Edition command line options is as follows:
cobolscript.exe [-i|-l] <program-name> [-t|-dd|-ds]
· The -i option runs the interpreter in interactive mode; see below for more information on running in interactive mode. When the -i option is used, if a program-name is not specified, interactive mode will be entered with nothing in the program buffer. If program-name is specified, interactive mode will be entered, and program-name will be loaded into the program buffer.
· The -l option runs <program-name> and creates a listing of the program execution as a separate log file with the name program-name.log. For example, if your program name is test.cbl, and you type the following at the command prompt:
cobolscript.exe –l test.cbl
then a log file named test.log will be created in the working directory.
· The -t, -dd, and -ds options are options that come after the program name:
Þ The -t option causes CobolScript to truncate (and ignore) all characters beyond the 72nd column position when parsing the program; this mimics the way mainframe COBOL works. Your program file is not affected, just the execution of the program. The default (no –t specified) is for all characters in the program to be treated as code.
Þ The -dd option causes CobolScript to recognize the double quote character ( “ ) as the string delimiter instead of the default, the accent symbol ( ` ). To display a literal double quote when using this option, your program must use the keyword DOUBLEQUOTE. The -dd and -ds options are mutually exclusive.
Þ The -ds option causes CobolScript to recognize the single quote character ( ‘ ) as the string delimiter instead of the default, the accent symbol ( ` ). To display a literal single quote when using this option, your program must use the keyword SINGLEQUOTE. The -dd and -ds options are mutually exclusive.
CobolScript Professional Edition also provides a utility to build executables from the command line, CobolScript AppMaker™. The syntax for creating an executable using AppMaker is:
cobolscript.exe -b <program-name>
If your program successfully loads, an executable will be created from it and placed in the working directory. For example, typing the following will create an executable named test.exe in the working directory:
cobolscript.exe -b test.cbl
CobolScript Error Messages in Command Line Mode
It will be normal for you to encounter bugs in your code while you are testing your CobolScript programs. In command line mode, error messages display directly to the screen in a text-based format. The error messages are quite specific, and will usually help you pinpoint the source of the problem with your code.
Multiple error messages are displayed when a single line of code causes multiple errors in the CobolScript engine; in these cases, one of these multiple errors should be obviously more specific than the others, and will better assist you in determining the problem than the more general messages. Multiple error messages, however, never indicate that there are unrelated errors on different lines of the program. This is because CobolScript is an interpreted language, and program execution is halted as soon as a single error is encountered. For this reason, you must re-run your program after correcting each error to determine if there are other errors in your code.
All error messages have an associated CobolScript Error Number, which displays along with the error message when the error is encountered; all error messages are explained in detail in Appendix F, CobolScript Error Messages, in order of this CobolScript Error Number.
After the last error message is displayed for a particular error, the text of the line that caused the error is displayed, along with some line number information. The Source Line Number is the actual number of the line in the program text file that caused the error. Use this line number to navigate to the line of faulty code in your program with a text editor like MS-DOS EDIT or vi. The Internal Line Number indicates the number assigned to the Instruction Pointer (IP) at the time of the error. This number can be used when a program is run in interactive mode to determine the problem line, in conjunction with the list and ip interactive mode commands. Finally, the Source Line is the text of the line that caused the error. Figure 2.5 shows an example of a command line error and the resulting error messages.
Running CobolScript in Interactive Mode
From CobolScript interactive mode, you can load a program, execute it, step through and animate its execution, and examine the contents of your program’s variables as they are populated. These features make interactive mode a great debugging tool. Interactive mode can be accessed by using the -i command line option when running CobolScript from the command prompt. Refer to the explanation of the CobolScript command line options above for the appropriate command line syntax. Figure 2.6 shows the start of a CobolScript interactive mode session on SunOS; interactive mode on other supported platforms is essentially the same.
Once you’ve started an interactive mode session, you’ll see the CobolScript interactive mode prompt that looks like this:
cobolscript>
From this prompt, you can use all of the interactive mode commands, although some commands will not work properly until a program has been loaded, and others will not work correctly until a program has been run. To see a help screen-style list of these commands, type a question mark (?) at the command prompt. Figure 2.7 shows a representation of this list of commands.
Interactive Mode Commands
The following list defines the interactive mode commands. Online command-specific help is also available in interactive mode by typing help <command>.
Interactive Mode Command
Description
?
Displays all of the commands available in interactive mode.
! `system command`
Runs a system command on your machine. The system command must be an operating system command in the appropriate syntax for your operating system. Examples:
! dir
! `dir | more`
! `ls –al`
! `chmod 777 test.cbl`
animate <speed>
Executes the code that is in the program buffer line by line, and displays each line of code as it is executed. The speed parameter controls the speed of the code interpreting and displaying process: the higher the number, the slower the lines of code will be displayed.
break <linenumber>
Sets a break point to halt program execution.
The break command has the following forms:
· break with no argument specified lists all current break points;
· break <linenumber> sets a break point in a program’s execution at linenumber;
· break clear <linenumber> clears the existing break point at linenumber;
· break clear all removes all existing break points.
clear
Removes the contents of the current program buffer. After the clear command is used, another program can be loaded into the buffer.
count
Displays the number of lines of code in the program currently loaded in the program buffer.
deskware
Displays Deskware, Inc. contact information.
display <variable>
Displays the contents of the specified variable. The display command can be used after run, animate <speed>, or stepon has been used to execute a loaded program.
dump variables
dump modules
dump positions
dump listing
Creates a text file dump of all variable contents, a module list, a program listing, or a variable position listing, depending on the argument. Below are the names of the files that are created by each command:
· dump variables - dump.var
· dump modules - dump.mod
· dump positions - dump.pos
· dump listing - dump.lst
files
Displays all of the files that a program used as it was executed. The files command can be used after run, animate <speed>, or stepon has been used to execute a loaded program.
help <command>
Displays command-specific help.
ip
Displays the current value of the CobolScript internal instruction pointer. This value is equivalent to the internal line number of the line that was just processed.
list
Displays the contents of the program buffer to the screen. The program buffer contains the lines of program code that were loaded with the load <filename> command.
load <filename>
Loads the contents of the specified program file filename into the program buffer. Once loaded, a program file can be executed by using the run or animate <speed> command.
modules
Displays all of the modules defined in the code that has been loaded into the program buffer.
positions
Displays all variables’ byte offsets. The positions command can be used after a program has been executed using run or animate <speed>.
q
Quits interactive mode.
run
Executes code that has been loaded into the program buffer.
save <filename>
Saves the current contents of the program buffer to a text file filename.
stack
Displays the code lines that are currently on the CobolScript internal stack.
stepoff
Turns off step mode that was set using the stepon command. After step mode has been turned off, the run command will run programs normally, without stepping.
stepon
Places CobolScript in step mode. Once in step mode, the run command will begin interactive execution of the loaded program. Interactive execution means that the program is executed, one line at a time, by pressing the ENTER key. As the program is interactively executed, commands such as variables, files, ip, and stack can be used to display current information.
variables
Displays all of the variables used by a program, and the contents of those variables. The variables command can be used after run, animate <speed>, or stepon has been used to execute all or a portion of a loaded program.
ver
Displays version information for your CobolScript installation.
Running CobolScript from a Web Server and Browser
With proper installation and web server configuration, CobolScript programs residing in the appropriate web server directory can be initiated by (and the output displayed in) a web browser. By placing your CobolScript programs on a server and accessing them with a browser, you can create graphical, efficient applications accessible from any computer with browser software installed on it, so long as the browsing computer has visibility to the web server computer, either across a network or the internet.
For your CobolScript web applications to run correctly, you should perform the following steps:
1. Place your programs, any text files used by your programs, and the CobolScript executable in your web server’s cgi-bin directory. Consult your web server documentation if you do not know where the cgi-bin directory is, or you want to modify its location.
2. On Unix servers, use the chmod command to change the permissions on the files that you placed in the cgi-bin directory, as necessary. Since CGI scripts usually run as user ‘nobody’, the permissions on these files generally must be set to allow any user to have the appropriate access to all files used by your programs. As an example, suppose a CobolScript web program reads from and writes data to a file named DATA.TXT. The file DATA.TXT must then permit both reading and writing by any user, in order for the program to run successfully. In this case, typing
chmod 666 DATA.TXT
at the Unix command prompt will change DATA.TXT appropriately.
3. Make certain CGI scripting is turned on and permitted by your web server software; this is necessary for CobolScript applications to run correctly. Consult your web server documentation for information on how to enable CGI scripting if it is not already enabled.
4.
After you have placed CobolScript and your CobolScript programs in your cgi-bin directory, you can execute the programs on the server with your browser by placing a “?” between the cobolscript.exe and the program’s filename in the browser URL. Figure 2.8 illustrates the execution of a sample timesheet program initiated from a Netscape® browser, but running on a FreeBSD® server with Apache web server software; note the address in the Location: (URL) box, that runs the program uts.cbl in the cgi-bin directory with the syntax “cobolscript.exe?uts.cbl”.
To generalize, any CobolScript program that has been placed, along with the CobolScript executable, in the appropriate directory on your web server’s computer can be executed by using a URL of the following form:
http://<your ip address>/cgi-bin/cobolscript.exe?<program name>
You can see several more example of this on the Deskware samples web site at http://www.cobolscript.com/cgi-bin/cobolscript.exe?samples.cbl.
CobolScript Error Messages in Web Browser Mode
Besides the standard command line error messaging system explained in the Running CobolScript from the Command Line section in this chapter, CobolScript provides an integrated web-based error messaging system. This messaging system is unique in that CobolScript determines whether you are running a program from a web browser or the command line, and controls the display of the error message accordingly. If you run a CobolScript program from you web browser and encounter an error, you will see the CobolScript Error Number and error message displayed in a consistent HTML-based format; if you run the same program from the command line and encounter the same error, the number and messages will display in a text-based format.
The web based error message in figure 2.9 illustrates this HTML-based error messaging system. In this particular example, a variable was misspelled in the GETENV statement, and was therefore undefined and caused an error.
Þ Ü
In certain cases when running CobolScript programs from a browser, you will see a completely blank browser window, or an incomplete display of your HTML without a CobolScript error on the page. These cases can indicate errors in your HTML code as well as a CobolScript error. Check the page source from your browser to find any CobolScript error messages that are embedded in the HTML but did not successfully display. Correct the CobolScript error(s) first; if the page still fails to display properly, but there are no longer any CobolScript error messages in the page source, check your HTML syntax.