Developing software for the SCP can many times be a frustrating, painful experience. For most folks, the first time one goes through the process, it seems extremely cumbersome, intimidating and obtuse. The goal of this document is not just to help “software virgins” over the intimidating hurdle of developing software for the first time, but also to detail and explain the necessary steps to help alleviate the inherent obtuseness of the process. Lastly, many of these hurdles are in existence because, as non-software folks, we will not be responsible for maintaining or repairing our code once it’s released. The imbalance of the sometimes tenuous relationship between code-writing non-software folks and the software department needs to be kept in mind as you push your way through this process.

If you are not a first-time reader of this chapter, please recall that Section 6.12 displays a summary of the needed commands, which you might find useful.

There exist many documents to help software folks write and test software. The most recent document of this nature is by Greg White; it is Chapter 8 of Conduct of Operations: Software Engineering , Volume #18-05 (there’s a copy in the MCC Library). Also, Principles of Operations (doc$poop:poop.doc) and Programmer’s Guide (doc$pg:pg.doc) sometimes contains useful information. All of these assume you have certain passwords and privileges that are not inherent to operator accounts. This doesn’t mean however that operators can’t or shouldn’t develop software. Rather, in the current situation, the procedure for developing software as performed by operators will differ from the procedure as outlined in the documents written by the software department. This document will attempt to put forth the procedure for operators (and potentially other miscellaneous non-software types) assuming their limited privileges.

Also, all examples of code or subroutine usages are in FORTRAN. It's not terribly difficult to write code in C or C++. In terms of understanding what a given subroutine does though, I think it's much easier to see when looking at its FORTRAN usage. Once one understands the basic usage, it's pretty easy to look at some C code doing the same thing, and figure out how it does what it needs to do.

This document will not attempt to teach you anything about the actual programming part, i.e. actually writing code. It will present to you the non-standard FORTRAN or C routines that you will need in your routine to interface with the SCP, but only to the extent to enable you to get a test shareable you can run as a SCP. In terms of other types of interface (like I/O), most folks find a button that does what they want, find the source code, then copy it. For example, if you want a toggle button to be a “pull-down” menu, find a menu button, find its source code, and copy it. To some extent, even if the correct usage of a panel write routine were explained, chances are, there are going to be some “tricks” to its usage. It’s best to find a working routine call, copy it, and appreciate that someone else spent the time getting it to work.

This document assumes you have the first five chapters of this document at hand and are familiar with them.

This document also assumes that the software change you make will be a SAME, not a MINOR or a MAJOR. The differences are as follows (almost direct quote from Conduct of Operations, Chapter 8):

SAME If there are no new entry points to this shareable; that is, no new routine is to be called by the shareable above this one.

MINOR    If a routine is being added to this shareable, and is to be called from other shareables, then an entry point (a.k.a. transfer vector)       must be added, and the release is a MINOR.

MAJOR    If transfer vector entries have been moved, a new page of transfer vectors have been added, or any collected common block has       been resized, renamed, removed , or added.

And if you don’t understand what all the entry point nonsense is about and you still don’t know by the time you’re ready to release, then you have made a SAME change.

The steps of the following long-view of the development procedure are all further expanded upon later in the document, in hopes that the later sections will, however, make more sense if you have seen a Big Picture.

1. Write some code to do what you want (usually in C or FORTRAN).

2. Compile your code into a development library.

3. Link your code with the rest of the current production shareable.

4. Run a development SCP and test your code.

5. Repeat steps 1-4 until you’re satisfied and your code does what it’s supposed to do.

6. Get your code changes blessed (either through the formal code review process (for a new subroutine) or through a back door (if it’s just minor modifications to an existing subroutine)).

7. Release your code to production (so everyone who starts a SCP can use it) with the help of a kindly software type with the necessary password.

As is stated in the Introduction, all commands to the computer are given indented after a “>“ in bold face. Parts of those commands that depend on each particular usage (like file names) are given in italics.

The partial listings of FORTRAN code (or other files) are given in Courier (“typewriter”) font to differentiate it from the rest of the document.

Yes, the SCP is one big program, but it is also a group of linked-together smaller programs called shareable images. If it weren’t for shareables, every time someone edited a subroutine, the entire SCP would have to be re-linked. By subdividing the code into smaller units, only the smaller units need to be re-linked at any given time. Then the big SCP program can just access these as needed.

That’s the general idea. The shareables represent a hierarchical structure of executables, all of which get called by the big SCP executable. See Appendix B for the graphic representation of this hierarchy. The shareables can call subroutines in all shareables “below” but not “above” them. This needs to be taken into consideration when choosing a shareable in which to put your code.

To call a subroutine in one shareable from another shareable, you have to create a transfer vector (the entry point stuff from above). This document assumes you aren’t creating new calls to other shareables. See Section 6.11 for a brief summary of transfer vector files.

The first step of any software development project is to determine if you can modify existing code or if you need to write a new subroutine. If your project involves a whole new functionality, you’ll be writing new subroutines. If your project involves enhancing the functionality of a given button push, you’ll most likely be modifying existing code. If you don’t know or can’t tell, choose the button on the SCP that comes closest to doing what you want done, then use the information immediately following to figure out what code is being called by that button. Take a look at the code and see if it meets your needs. When all else fails, please ask for help before giving up.

Most of the following information is coming from the Basic User’s Guide (a.k.a. BUG). See Section 3.3.7 for a similar explanation.

Once you have a specific button in mind that you want to find the source code for, you’ll first need to get the panel name. With the panel selected on a SCP, hit the HELP button. This should list at the top of the graphics window the name of the panel. This file will live in SLCPNL:file_name.PNL. Now check out the line of text associated with your button. It might look something like:

button: 0,0,label(18 chars),btn_name,var_name,sbr_name,dsp_name,i

The word button might be any of the following choices: button, script, switch, select, shadow, assign, deassn, spawn, or unspwn. For our purposes, we don’t really care. What we do really care about is sbr_name, which is the name of the subroutine that gets called or a logical pointer to the subroutine. Every time a button gets pushed, btn_name, as a string of 8 characters, gets loaded into the variable var_name and the subroutine sbr_name gets called. The usual process involves the subroutine reading what’s in the variable then determining what to do based on btn_name. (These symbols are further explained in Section 6.3.4)

Trying to look through almost 50 directories for a piece of software who’s name is vaguely reminiscent of the 8 characters in the panel code is unappealing at best. Luckily, multiple COM files exist to help you out. The five main ones are listed below with a general explanation of what each does:

FIND_LOGICAL    searches a table of SCP logical names constructed from the arguments to all LIST_* and APP_REGISTER calls found in source code.

FIND_ENTRY    searches a table of entry names to locate the corresponding source file(s).

FIND_REFERENCE    searches a table of external references to locate the corresponding source file(s).

FIND_SOURCE    searches both of the above tables for the specified source file name(s).

FIND_LIBENTRY    searches a table of object library entry names to locate the corresponding object module(s) and library file(s)

The one most likely to be useful for this specific application is find_logical. Because both the 8-character subroutine name and the 8-character variable name are logicals defined with list_call, list_var8, or app_register, they should come up with find_logical. Common usage is:

>find_logical variable_name

This will list for you a table with the following columns: type, logical name, variable or entry, and source file. Type will be one of these: VAR4, VAR8, TP, DISP, or SCHED. These refer to calls to list_* except for TP, which refers to a LIST_CALL. The logical name is the 8-characters from the panel code, the variable or entry gives the actual name of the variable. The source file column gives you the shareable name in square brackets, with the source code file following, like [CRRSHR]RPN_DRVR.FOR. To copy this file to your space, from your space type:

>copy ref_crrshr:rpn_drvr.for *

The ref_shareable_name directories are read-only. You need to keep this in mind if you set default. Always edit code from your working directory.

Whocalls is a program like lookfor that searches for calls to and from a specific subroutine. The usage is:

>whocalls subroutine_name

It displays two columns of information: referenced by and calls. The subroutines listed under “referenced by” call the subroutine you’re curious about. The subroutines listed under “calls” are called by the subroutine in question.

This is particularly useful when you know you want to call a specific subroutine (panel write, for example) and want to find other subroutines that call the desired routine so you can just copy the usage.

FIND_REFERENCE works similarly if you want to try that out.

Why do all the list_xxxx subroutines exist?

Simple answer: the fields in the panel code are eight and only eight characters long. If you write a subroutine with a nice descriptive title, chances are the title going to be more than eight characters long. Thus, the clever folks who designed all this in the first place, wrote some very useful routines to make eight potentially nonsensical characters point to a subroutine or variable (or display) with a nice, longer-than-eight-characters title. Check out section 2.3 in BUG for the low down on the list_ subroutines. These will also be referenced later in this document because you will have to use one of them if you create a new variable, subroutine, or scheduled display (even if it’s nice, descriptive title is only 8 characters long...)

Since January 1996, folks who write software have been “encouraged” to use APP_REGISTER instead of a LIST_xxxx subroutine. The first argument passed to APP_REGISTER specifies if you want to “list_call,” “list_disp,” or “list_var8,” etc. In fact, list_call, et. al., have been rewritten to call APP_REGISTER. Good examples of how to use this subroutine and the routine itself are in ref_dspshr. It’s rumored that Ralph Johnson has documentation on it and could be potentially bugged if you have problems. Your best bet though is to copy by example.

The rest of this document will refer to the list_xxxx routines, in part because all the old code (in existence before January 1996) uses these routines. Also it’s easier to talk about list_var8 than about app_register with app_var8 as the first argument.

Again, you are strongly encouraged in all new code to use this routine.

Once you have your hands on a subroutine you think you want to edit, most folks create a working directory in which to put a copy of the existing subroutine. Now all you need to do is edit it until it looks like you want. Once you’re sure that it’s perfect, go to Section 3.5 to compile and link your code.

A working directory is necessary because (1) the files are in CMS, (2) you don’t/can’t release code every time you need to test it, and (3) the files are huge.

If you were a software type, and only one of a couple folks working on the code in a specific shareable, you would reserve your code from CMS before you started, to make sure no one made any changes underneath you while your code was in development. Then once everything is tested and ready to go, you replace it then release.

That’s not really a viable choice given the manner most non-software folks work on code (and the fact that most folks don’t have the necessary privileges on their accounts). You need to be aware though, that folks might change the code “underneath” you while you are making your changes. Always do a difference to existing code before reserving, replacing and releasing. This point will be made again in the section on releasing code.

If you know that you’re going to be very fast modifying a piece of code, you might want to reserve it first. You can try to reserve it yourself, ask Nancy Spencer for the privilege to reserve files for your shareable, or ask a nice software person to do it for you.

As mentioned previously in this document, the default quota of operator accounts is hideously small. In your working directory, before all is said and done, you will have not just your code and other small routines to help make a test SCP, but also a test executable of your shareable. These executables range in size from 12 blocks to 12,838 blocks, as of this writing. And they get bigger every day. When you create these monster executables, also created is a MAP file. These usually range in size from 300 to 800 blocks.

When Mark Woodley wrote the flight simulator, which uses 3 shareables, he created a directory for himself on user_disk_mcc. (Just the source code plus executables for the FFFS is 15,000 blocks). Other folks have created spaces for themselves on other non-quota disks. An obvious choice is to create your own subdirectory of MCCSCP’s home directory. The advantage to this is that MCCSCP is logged in all over the control room all the time. The disadvantage is that it’s hard to figure out who actually owns the MCCSCP files, and many times stuff gets erased by someone who doesn’t own the files. It doesn’t really matter however. PLEASE if you need to do this, keep your disk usage as little and as efficient as possible. Don’t keep seven versions of TST_DCXPSHR.EXE (at 12,800 blocks a pop) floating around your directory. There have been a couple instances of pleas from software folks to get user_disk_mcc and [mccscp] space cleaned up. Be a responsible user. Also if you need a lot of disk space for a long time, talk to Terri Lahey first. She might have some better options in terms of storage places.

Ideally, you would talk to the Disk Quota Goddess, inform them that you’re now doing some software development, and *poof* they would grant you the 30,000 blocks necessary for any real software development project. It’s probably worth your while to ask.

If you have determined that you’ll need a new subroutine, or are creating new functionality for the SCP, most folks usually just jump in and start writing. You’ll want to have a working directory in which to work. See Section 6.4.1 and 6.4.2 above for points to consider about working directories.

There are a few extra steps to do when writing a new routine versus editing an existing one. These include choosing a shareable, putting a list_call for your routine in the right place, using list_var8 if you’re creating new panel variables, and if you’re creating a new include file, there are some points to consider that are different from standard FORTRAN or C usage because of the shareable set-up of the SCP.

If you’re writing a new subroutine, your life might be easiest if you choose a mentor of sorts from amongst the software types. I mention this here because their knowledge and experience would greatly facilitate your choice of shareable, especially if you’re creating a new functionality to the SCP.

The primary piece of information to consider getting on the appropriate level of the shareable hierarchy is to determine which routines you’re going to need to call. Are you just going to munch already existing data in a novel way? Are you going to have to write information to the panel? Are you going to need to make pretty displays? Your subroutine will have to live in a shareable “above” all the subroutines it needs to call.

Yes, you need to think about this, but you don’t really have to sweat it too much. It’s not hard to change what shareable you put your code in. Also no one in software is going to let you release your code (or even give an OK to your code during code review) if it’s in the wrong spot.

If you’re choosing a shareable by yourself, but your code won’t link because it can’t find a routine you’re trying to call, choose a shareable higher up the ladder and try again.

Also the shareable choice should be “logical.” Don’t put a new CRR data fit in the wire utility shareable, even if it does let you link from there.

Your choice of shareable is manifested as a “member card” in the very beginning of your subroutine. Check out a piece of code from your chosen shareable to get the format and placement (it looks like a comment line containing “**MEMBER**”). If you need to change your shareable (i.e. it won’t link because it can’t find a routine you need to call), all you have to do is change the member card, recompile, do another MAKE_SHRINIT (see below), and link again. It takes time but is relatively painless.

All shareables have so-called INIT files. These files usually have a title that starts with the first three or four letters of the shareable name, the letters: “init”, then the file type FOR (usually), like DSPINIT.FOR or CRRINIT.FOR. These files contain the calls to the logical name routines LIST_DISP and LIST_CALL for all the displays and subroutines in that shareable. As you are going to be adding one to this list, you’ll need to modify this subroutine. Get a copy of it for your working directory and add a list_call with your subroutine name and 8 character sbr_name of choice. You’ll also need to declare your subroutine “external” at the top. Follow an example in the existing code.

If you find that after linking your development SCP, that it didn’t link with your INIT file (i.e. when you push your button it can’t find your subroutine), you might need to get your shareable’s shareable_GENERAL.OPT file from SLCSHR_CONTROL. Sometimes the INIT files are “included” in this build file. Copy the OPT file to your space and go from there. See the section (0) on buildtest below for how to link.

If you need to create a new panel variable, you’re going to need to call list_var8 with the 8 character string var_name and the variable local for your subroutine to point to. In FORTRAN this looks something like:

INTEGER*4 LIST_VAR8

CHARACTER*8 SUB_VAR

ISS = LIST_VAR8(REF%(SUB_VAR),'VAR_NAME')

After this point, you can do tests based on the value of sub_var.

IF (SUB_VAR .EQ. 'BTN_NAME') THEN ...

This looks quite a bit different in C. As I don't completely understand all the hoops (one needs to jump through), I would check out a C code in CRRSHR or FFOPTIC and copy what Greg or Lee Ann did.

If you are making a LIST_CALLed subroutine, you will need to build into your subroutine what to do during initialization of the SCP. There is a standard test using the parameter ACNTRL to determine if your code is called via SCP initialization, panel initialization or just a standard button push. In FORTRAN:

    INCLUDE 'SLCTXT:ACNTRL.TXT'

    IF (ACNTRL(1).EQ.ACNTRL_INIT) THEN

C    LIST_VAR8s and only LIST_VAR8s should appear in

C    this space!!!! (don’t forget to use app_register in

C    new routines...)

    ISS = LIST_VAR8(REF%(SUB_VAR),'VAR_NAME')

   ELSE

C    the rest of your subroutine goes here

   ENDIF

   RETURN

   END

If you have something that needs to be done every time the panel is called (like put some information on a button or display some numbers on the panel) or have panel code with a * at the end of the line (which means that line should be executed every time the panel gets pulled up), do a test for PNL_NEW.

    INCLUDE 'SLCTXT:PANEL.TXT'

    IF (PNL_NEW) THEN

C       do your displays/panel writes here

    ENDIF

To do initialization of variables, don’t do it in the ACNTRL_INIT space. This space is reserved for the list calls. If you put lots of stuff here, SCP initialization will take even LONGER than it does now. The accepted way to do initialization is to create a logical initialized to true that you set to false after initialization.

    LOGICAL*1 FIRST

    DATA FIRST /.TRUE./

    IF (FIRST) THEN

       FIRST = .FALSE

C       do your initialization of variables here

    ELSE

C       rest of your subroutine here

    ENDIF

Both the PNL_NEW and the FIRST test chunks of code will be nested into the ELSE part of the ACNTRL_INIT test loop.

All include files for the SCP live in SLCTXT. This is a logical pointer to both the SLCTXT directory and the C_INC directory (which has the .h files). These files are in CMS in the library: CMS_SLCTXT. If you need to change an include file, keep a copy in your working directory until you’re ready to release. Make sure to replace the include file before you start to release your code so that everything compiles with the right include file...

If you do change an include file, you’ll need to recompile/relink all subroutines that include it after you’ve replaced the include file.

The default setting for FORTRAN common blocks is SHR, i.e. share mode. However, given how we run the SCP program, we want each SCP to have its own version of the common block, unique to that SCP. Thus, if you create a common block that shouldn’t be shared between SCPs, you need to put a command at the end of the include file containing your common block to make it NOSHR:

CDEC$ PSECT /common_block_name / NOSHR

In FORTRAN this begins in column 1. Check out an existing include file for examples.

Common blocks can only be shared by modules in a given shareable. Modules in other shareables can’t get at the common unless it is “collected” which entails a MAJOR release.

Once you have some code that you’re happy with, the next step is to compile. First you need a place to put the object files so the special link-up-a-test-shareable COM file can find them. This development object library is created with the command:

   >lib/create devlib

This will create a file, devlib.olb, in your directory. Check out the VMS help library command for more information on working with libraries. (See Section 3.11.3 too for basic commands.) At some level, this is the only command you need to know. If something weird should happen however, it’s nice to know where to get some help.

There are three commands to compile your code and stuff the OBJ files into your devlib. These are CCHK, CINC, and CDEV. There are minor differences between them.

CCHK is the “preferred” method of compilation. It uses the compiler options: list, no print, check boundaries, flint, abort, and no optimize. Flint is a program for FORTRAN, like lint for C that checks your code for mistakes that will hang up the compiler or inconsistencies in the code, like creating a variable that you never use. The NOOPT option is nice if and when you use the debugger to check out your variables. The CHECK option makes sure your array boundaries are all kosher. LIST creates a .LIS file, and NOPRINT makes it so nothing gets printed. ABORT tells the computer that when compiling more than one routine, if an error is found to stop the compile command (i.e. not keep compiling the other routines in the list). CCHK is action looks like:

    >cchk file_name

If you don’t like the default options you can change them by listing them after:

    >cchk file_name NOOPT NOA PRINT NOL

Per usual VMS usage, wildcards are usable within the file_name field.

CDEV uses the default compiler options: list, no print, no check, no flint, and optimize. Again you can change these to meet your needs.

CINC is like CDEV in that it uses the default compiler options, however it also uses the include files in your directory preferentially to those in SLCTXT.

A shortcut exists called devmaint. It examines the date stamps of object files in any existing DEVLIB and uses CINC to compile all corresponding source modules in the local directory that have since been updated. You still have to CINC/CCHK/CDEV the first time, but can devmaint every time there after. Usage:     >devmaint

As of February, 1999, it is reported that this function is no longer available. It was used once you had successfully compiled your code so that you could link it into a test shareable. Previous versions of this document will contain the syntax information but this revision does not.

The actual link command is:

    >buildtest shareable_name

This creates two files: tst_shareable_name.exe and tst_shareable_name.map.

If you’ve had to edit your shareable’s shareable­_GENERAL.OPT file, the buildtest command gets modified:

    >buildtest shareable_name /default

NOTE: If you just did a buildtest then you don’t need to TESTSHRX.

Before you SCP, you need to define logicals so that the actual SCP command goes and gets your test shareable, but all the other shareables from production. This command is:

    >testshrx/default =dir_name shareable_name

for example:

   : >testshrx/defa=user_disk_mcc:[mccscp.mydir] crrshr

This will tell the SCP to get the crrshr shareable from user_disk_mcc:[mccscp] instead of production. This logical is defined for the process or DECterm from where you typed the command. Before you leave for the day, you should be nice and undefine the logical with the command:

    >testshrx/deassign shareable_name

Or even better, create a COM file that anyone can run that does the testshrx/defa, scp, then testshrx/deas. The following COM file was stolen from the Flight Simulator.

$ TESTSHRx/DEFA=USER_DISK_MCC:[MDW.FFFS] FFOPTIC

$ DEFINE SLCPNL USER_DISK_MCC:[MDW.FFFS.SLCPNL],SLC_PNL

$ DEFINE DEVSCP_NAME FFFS

$!

$ @SLCCOM:SCP

$!

$ TESTSHRx/DEAS FFOPTIC

$ DEASSIGN SLCPNL

$ DEASSIGN DEVSCP_NAME

This file is spiffy for many reasons. First, from any directory on any machine, you just type @user_disk_mcc:[mdw.fffs]fffs and you get a Flight Simulator SCP. Second, there are two logicals being defined to make the user’s life much easier. The SLCPNL definition (see Section 3.3.6) has the SCP use the panels in his “SLCPNL” directory before getting those from the real SLCPNL directory. The user has to toggle to “ USE .PNL” on the USER DEV PANEL to enable this option. The DEVSCP_NAME logical defines the string of characters that shows up in reverse video on the Index Panel button on Dev SCPs. It usually says, “DevSoft,” but you can change that. Third, after you exit the FFFS SCP through the normal process, the COM file deassigns all these logicals so the next user won’t get screwed up.

If your code is running on a test scp, and it’s not doing what you think it should, you might want to get into the debugger and poke around to find out what’s wrong. The VAX/VMS folks wrote a perfectly good manual on how to use the debugger. It lives upstairs on the second floor of MCC, with all the other manuals. However, there are a couple extremely vital commands that are necessary to debug SCP code.

There are two ways to get into the debugger: start the scp with the command: run/debug slcimage:scp or CTRL-Y in the DECterm of an already running SCP and type debug. At the debug prompt, you’ll want to set a break point at the start of your code. There are four commands to do this (and one is a trick, so pay attention!):

DBG>set image shareable_name

DBG>set module subroutine_name

DBG>set break %line 2

%DEBUG-E-LINEINFO no line 2, previous line is 1, next line is 419

DBG>set break %line 419

DBG>go

This will put the break point at the first executable line of your subroutine. The appropriate line number (419 in the example above) can be found in the LIS file or by using the set break %line 2 trick as in the example. (That’s an LJH special, by the way...)

Once the SCP breaks on your subroutine, all the standard debugger commands do what they’re supposed to.

All source code for the SCP has to meet the code standards as put forth in: code_review.mem, stds_vax_c.mem, and stds_vax_fortran.mem. These live in the doc$standards directory. These MEM files are directly printable.

Bringing one’s code up to spec is really important. Remember, if your code bombs, especially in the middle of the night, it’s some poor software person who is going to get called in to fix it. It’s very important to write code that is maintainable by someone else. Also once your code is released, it becomes the software department’s responsibility. Don’t be a delinquent parent.

Once your code complies with the standard code guidelines, you need to get your code blessed. There are two entrances to the Church of Code, the front and the back.

If you have written a brand new subroutine, you need to use the front door.

The file you will need is: slccom: submit_code_rev.com. Execute this COM file from MCCDEV (it won’t work from MCC) and enter the requested data. It doesn’t hurt to have talked to Ron Chestnut close to the time that you do this, just to make sure he knows.

This file will assign your code to a reviewer. You will be notified by e-mail. You might want to be in e-mail contact with the reviewer to get a time scale about when you can expect the review to be complete.

Another related file you might find useful is slccom:find_my_code_rev.com. This file will prompt you for reviewer and coder and give you the status of your code review.

If you have done minor modifications to an existing routine, you don’t need to go through the full-blown code review process. Usually before releasing, you get an OK from the “owner” of the code. I usually chat with Nancy Spencer for a bit to determine who the “owner” is. Now you send e-mail to the person with the holy water and hope they’re not so terribly, terribly busy that it takes them more than a week to read your dozen lines of code.