Re: The list of INVOKEs

Charles Hottel wrote:
"Pete Dashwood" <dashwood@xxxxxxxxxxxxxxxxxxxxxxxxx> wrote in message
news:79pc9sF1rpj0vU1@xxxxxxxxxxxxxxxxxxxxx
Charles Hottel wrote:
"Michael Wojcik" <mwojcik@xxxxxxxxxxx> wrote in message
news:h15r4t02i9m@xxxxxxxxxxxxxxxxxxxx
Charles Hottel wrote:

IIRC I think Richard codes HTML documentation in his COBOL
programs and has
a program he uses to extract it. I guess this is similar to
Javadoc. I know Donald Knuth was an early promoter of literate
programming and wrote a
book about it. I think he used TEX and had two programs called
WEB and WEAVE.

Yes, but embedded documentation markup, as with Javadoc and
Doxygen, is a far cry from Literate Programming.

We discussed this a bit a while back, in the context of my ATTW
presentation. See [1].

Knuth's use of TeX in his original Literate Programming system
(which did indeed use a pair of programs named WEB and WEAVE) was
perhaps its greatest failing. The output of the system was
compilable source and a lovely typeset document explaining just
what it did and how; but the actual source that a maintainer had
to understand was a nightmarish jumble of TeX macros, completely
incomprehensible to anyone who hadn't memorized TeX syntax.

Two steps forward, one step back...


[1]
http://groups.google.com/group/comp.lang.cobol/msg/1b9c5eef57c7756d
-- Michael Wojcik
Micro Focus
Rhetoric & Writing, Michigan State University

Yes, even though I have written programs which have produced
typsetting commands in several different typsetting languages, I
found his books on TEX and METAFONT hard to follow. Even if you
understand the basic stuff he has many macros that you need to learn
to understand his preferred formatting style. Perhaps what you
mentioned above is why it has not seemed to catch on. It is too
complicated and many programmers are not interested in producing
good documentation. They seem to view it as overhead or a chore. I
think maintenance programmer's may appreciate good documentation
more than some others. My editor, ROSCOE, is old and many would
say archaic, but the line commands "nc" and "na" (note COBOL and
note Assembler) greatly speed up and ease the creation of embedded
program comments.

Good Heavens, Charlie, I thought ROSCOE was long gone... :-)

Part of my job back in the days when I worked for IBM in
Southampton, U.K. was to write ROSPROCs to support our local
development. (I copped this job because I was the only one who knew
it :-)) Eventually, of course, they moved to TSO but ROSCOE served
them well for many years.
<snip>

Well ROSPROCs were pretty cryptic but they have been replaced by
Roscoe Programming Facility (RPFs) which is much better (more similar
to REXX). I maintain some that everyone uses to generate their
compile JCL. Not many people know the RPF language and most are not
interested in learning it. These RPFs are supposed to be replaced by
some Dimension's stuff. They need to do that before I retire or I do
not know who will maintain the RPFs.

Not your problem really is it? :-) You are doing your job; it seems they may
not be doing theirs...

I guess you could point it out (in an email, so there's a written record...)
and that would entirely meet any obligation you could be considered to have.


Apparently Java is no panacea or else the contractor consortium
developing the new, replacement systems is poorly managed.

Hmmm... I agree Java is no panacea, but then again, neither is anything
else. Against poor management the finest technology in the world can end up
looking inadequate. The poor management MAY be on the part f the Consortium,
but what about the management at your place? Did they have a clear idea of
what they wanted and did they specify it properly in a RFP? What checks and
balances are in place to ensure the performance they are paying billions
for? My point is that "poorly managed" rarely tends to be on one side... If
a company or organization is well managed and they go to tender, they will
pretty soon pick up problems with the contractors, (irrespective of how
illustrious these contractors may be), if those contractors are NOT well
managed. I saw a major Insurance company in the U.K. cancel a contract
(after one year of what was going to be three years) when they realised that
the household name they had contracted the task to was going nowhere. The
Insurance company was very well managed and they had independent consultants
(like me) employed to assist and monitor the contractor effort and make sure
it stayed on track. It soon became apparent that the contractors were using
it as a testing ground for their latest software and they were much more
interested in debugging and enhancing their own packages than in providing
service to the Insurance company. (In effect, the Insurance company was
picking up the R & D for the contractors...)

Nothing much was being achieved. There were some frank discussions round a
table with managers from both sides present and concerns and issues were
raised, promises were received and everyone went back to work. Two months
later the promises had all been broken or never kept and the contractors
turned up to work to find their terminals inaccessible and themselves
escorted from the premises with all work done remaining the property of the
Insurance company. (We were able to salvage about 60% of it, so it wasn't a
total loss, but it cost the company a lot of money. Still, nothing like as
much as if the fiasco had been allowed to continue.) My opinion of the
Insurance company was strongly reinforced by their decisive action. A less
well managed company would have been conned into persisting to the end, and
probably to extend the contract when it became apparent that the original
goals failed to materialize.

They put
a new subsystem into production some months ago. It was over six
months late going in and they are having a tremendous amount of
problems that need to be fixed. So much so that the development on
the new subsystem to replace our existing subsystem, which was
already well under way, has been stopped and a lot of contractors
have been layed off.

If a project is haemorraging cash, it is sometimes necessary to stop the
bleeding before taking stock. There is always a danger of good stuff being
discarded with the dross, but often that is an acceptable risk. If proper
management is in place both of these events should be unlikely.


This is probaly all my fault. They sent me to a Java class and right
after that all hell broke lose.
LOL!

Extremely unlikely...

This happened before back around
1992-1993 when they were planning to use C++. I took a C++ class and
the next thing I know they cancelled everything because they decided
they could not afford the tiered architecture of Unix servers. I
never understood why they couldn't determine that up-front before
they started.

Precisely. It seems to me that the problems are not all on the contract
side...

Anyway all of this greatly increases the chances that
I will retire before our system is replaced. This might even seem
funny except for the billions of dollars that have been spent. At one
time they had 700 to 800 contractors devopling the new system.

Did Arthur Andersen have a hand in this... :-)

As far as extracting commens/documentation from COBOL programs, I can
use the command: DELETEX 7 7 /*/ which deletes everything except
lines with an asterisk in column 7. When I read Michael's
presentation I noticed that he preferrs using mixed case letters, but
I prefer uppercase letter as it is simpler to search for words using
ROSCOE. Of course I can convert all to uppercase before searching
but I am basically lazy.

Most of us are "lazy" inasmuch as we don't like doing more than we have to,
but on this occasion I would urge you to make a little more effort :-)
Michael is right about mixed case; it is definitely more readable. After
working in mainframe environments where ONLY upper case was available, I
thought COBOL looked "strange" when written in mixed case, but within a
couple of weeks I was persuaded otherwise. The old Internet injunction
("there's no need to SHOUT!) is pretty true at some level for most of us.


I seldom extract the comments but I have
RPFs that can search all members in a PDS, all members in a Librarian
dataset or all members in a ROSCOE library for whatever string I
desire. This has come in handy on many occasions.

A feature served by global editing that many a programmer has been very
thankful for. In Visual Studio you can find/replace not just in the current
document, or all the open documents, but all the FILES in the project as
well (Your call...).It has been a boon on a number of occasions when I
decided to change a name, or even change an output message that could be
present in more than one library. Make sure you keep a copy of these RPFs
for yourself, Charlie. You never know when they may come in handy.

Pete.
--
"I used to write COBOL...now I can do anything."


.

Relevant Pages

  • Re: The list of INVOKEs
    ... I agree Java is no panacea, but then again, neither is anything ... Against poor management the finest technology in the world can end ... tender, they will pretty soon pick up problems with the contractors, ... I saw a major Insurance company in the ...
    (comp.lang.cobol)
  • Re: convincing a client to go with dotNet instead of Access project
    ... That would be good documentation to have... ... > -learning curve for language, APIs, deployment management, etc ... > -Access really tops out with performance after six concurrent connections ... >> I believe a dotNet solution is better, but I'm trying to be as ...
    (microsoft.public.dotnet.general)
  • Re: How do i write Set based queries and avoid a cursor?
    ... it involves a product or service they are libel for? ... considered an "uninteresting attribute" by management or the lawyers. ... improve the quality of the documentation in just a few minutes: ... Imagine a DB app that calls a webservice to check address against postal ...
    (comp.databases.ms-sqlserver)
  • Re: Knowledge Management on the Windows Platform
    ... They will sell me a knowledge management system, ... somewhere behind the technology that Microsoft exposes to the generic user / ... In that documentation would be explained the utility value, ...
    (microsoft.public.windowsxp.general)
  • Re: About PDM Software.
    ... > all our engineering data. ... IIRC MKS used to do concurrent ... considering automating the management of the information. ... All documentation should be subject to the ...
    (comp.arch.embedded)