Trailing-Edge - PDP-10 Archives - tops10_integ_tools_v4_10jan-86 - 70,6067/isacon/isacon.mem
There are 5 other files named isacon.mem in the archive. Click here to see a list.
ISACON Documentation						Page 1


	ISACON is a small system designed to aid in the conversion of
	TOPS-10 and TOPS-20 ISAM files to VAX/VMS RMS files.  It is a
	tool designed for use by programmers in the midst of a COBOL
	conversion effort.  It generates COBOL programs which will: 

	a) convert a user's ISAM file into a sequential ASCII file, 
	b) convert the sequential ASCII file into an indexed RMS file, 
	c) create a dictionary to be used with Datatrieve for this file.

	The primary architecture specific features in ISAM files on the
	TOPS-10/20 systems include the following: inclusion of binary
	(computational) fields in the file, sixbit files, 128 word or
	512 word blocking factors, computational fields redefined as
	display.  ISACON resolves some of these by reading the ISAM file
	sequentially and moving it field by field into an unpacked,
	unblocked ASCII file before it is moved across systems.
	Similarly, the ASCII input file is moved, field by field, into
	the destination RMS file.

	An important feature of this system is the creation of the
	Datatrieve dictionary for the RMS file.  This is done by running
	the dictionary program generated by ISACON and giving its output
	as input to Datatrieve.  This will allow the RMS file to be
	referenced from a variety of other tools which know about the
	VAX/VIA architecture.

ISACON Documentation						Page 2

                           Installation Instructions

	There are two COBOL programs and three skeleton files in ISACON.
	They are to be installed on your TOPS-10/20 system.  The COBOL
	programs are in COBOL-74.

	The EXE's and SKL's should be installed in a Library directory
	which is accessible to the programming staff.  The COBOL
	programs always search DSK for the necessary files.  Since
	sources are included, you have the option of defining DSK to
	include the library directory or changing the select clause on
	the program.

	Since this system generates COBOL programs, it is recommended
	that you examine the skeletons for any parameters you wish to
	change.  The skeletons included with this system are in ASCII
	and designed to be tailored by each installation.  In
	particular, the Environment Division site definitions should be
	changed.  You may decide to make other changes to the skeleton,
	such as logical name definitions.

	The principle behind the skeletons is Macro style definitions of
	how to generate code.  (The word "Macro" is used here as a set
	of instructions to be generated upon occurrence of specific
	verbs.)  As a consequence, the definitions of the code to be
	generated are delimited by "{" and "}".  The skeleton contains
	tokens which are found by the analyzer and used by the
	generator.  Inserting additional tokens is a complex procedure,
	changing the action performed by the tokens is easier.  However,
	any changes to the skeleton should be made with extreme caution
	and tested thoroughly.

ISACON Documentation						Page 3


	The first program in the series is used to analyze your existing
	file description and create a File Language (.FL) file.

	Prior to invoking VAG001 you must first find a COBOL program
	which uses the ISAM file to be converted.  This program must
	then be compiled to produce a listing (.LST) file.  This listing
	file is the input to VAG001.  By using the .LST file as the
	input description we are assured that the entire file
	description is present in one file.

	The program VAG001 asks for only three inputs, the file name for
	the listing file, the select name in the environment division
	and the name of the output file language (.FL) file.  VAG001 is
	structured so that multiple programs and multiple selects may be
	extracted without exiting the program.

	To run VAG001, simply type

	.RUN VAG001

	It responds with

	Listing file >

	At this point a return exits the program, a question mark gives
	you a help message.

	The expected response is the listing file of a program using the
	ISAM file(s) to be converted.  The format for the response is
	<filename>.<extension>.  Since this is a COBOL program
	<filename> may not exceed six characters in length and
	<extension> cannot be more than three characters.  If an
	extension is not entered, VAG001 defaults to "LST".

	For example:

	Listing File >MYFILE.LST

ISACON Documentation						Page 4


	The next prompt displayed is:

	Select name >

	A return will give you the Listing File prompt, a question mark
	will provide you with help.

	The expected response is the name of the ISAM file within the
	program's Select statement.  For example, if your program


	You must type in VENDOR-DEMOGRAPHIC-FILE in response to the
	Select Name prompt, as per the following example:


	Note: Currently VAG001 does NOT do a partial match.  Therefore,
	the file name must be entered in its entirety.

	The next prompt is:

	File language (.FL) name >

	A response of return will get you back to the previous prompt, a
	question mark will give you some help.

	The response to the this prompt is a <filename>.  This
	<filename> can only be six characters, and is expected to be the
	same <filename> as the current ISAM file to be converted.  It is
	also used as follows:

	A.) It will create file with <filename>.FL which contains the
	description of the ISAM file to be converted.

	B.) The next program in the series (VAG002) will create COBOL
	programs with <filename>U.CBL, <filename>L.COB and
	<filename>C.CBL.  Where the U,L and C will be the last letter in
	the filename, if the filename is 6 characters long, then it will
	replace the last letter with one of these three.

	C.) The programs mentioned above perform an unload, load and
	Common Data Dictionary creation for the ISAM file.  The files
	they look for are <filename>.IDX and <filename>.IDA on the
	36-bit machine and they create <filename>.IDX on the VAX.

ISACON Documentation						Page 5


	The second part of ISACON is the program generator VAG002.  Its
	input is the File Language file generated by VAG001 and one of
	three program skeletons.

	How to use VAG002.

	In order to run VAG002, you must have the file language file
	<filename>.FL, the load skeleton LOADIT.SKL, the unload skeleton
	UNLOAD.SKL, and the create dictionary CDDICT.SKL in you DSK
	search path.  You then simply run VAG002 as follows:

	.RUN VAG002

	It then asks for the file language file name:

	File language file >

	A return will exit the program, a question mark will give a help

	The response of <filename> will open <filename>.FL for input.

	The program next asks for which skeleton you wish to use, as
	mentioned above, you have a choice of three which are supplied
	to you.  They are UNLOAD, LOADIT and CDDICT.

	For example:

	Skeleton > UNLOAD

	A return will return you to the file language prompt, a question
	mark will give you help.

	The following is a complete sample dialogue for VAG002:

	.Run VAG002

	File language file > HIST
	Skeleton > UNLOAD
	Skeleton > LOADIT
	Skeleton > CDDICT
	Skeleton >
	File language file >


ISACON Documentation						Page 6


	This will leave the following files in your directory:

	These programs are now ready to run.  The unload and dictionary
	program can be run on your DEC-10/20.  The load program is
	strictly for the VAX.

	Customizing generated programs.

	COBOL programs are generated to perform data conversion because
	it is quite likely that your file will contain something which a
	generalized program cannot handle.  The following are some
	examples of the cases requiring modification of the generated

	A.)  You have fields redefined in the file, and some of the
	redefined fields are display in one case and computational in
	another. You will have to redesign the record on the VAX.  You
	will also have to change the generated program to move either
	the computational or display fields depending on whatever
	criteria already exist for making this transition.

	With ISACON you have the option to either move all redefined
	fields, or not.  The default is to NOT generate the moves for
	any fields under a redefined clause.  If you wish to have ISACON
	generate the "Move" statements remove the "/IF {REDEF}" and its
	corresponding "/END-IF" from the skeletons.

	B.)  Your actual record definition is in the working-storage
	section, rather than the file section.  The recommendation for
	this is to move the record definitions under the FD.  This will
	generate most of the code you need.  You can then add your
	statements to take the various record types into account.

	C.)  Your original system designer was really clever and wrote
	an assembly language routine to pack switches into characters.
	In order to convert this, you will need to unpack these fields
	into the sequential ASCII output.

	D.)  You want to use this program with sequential files, rather
	than ISAM files.  This involves trivial changes to the generated

ISACON Documentation						Page 7

                          Common Data Dictionary Notes

	Under the VMS architecture it is possible to enter a record
	description into one place (the Common Data Dictionary) and have
	it accessible by a variety of languages and tools.  ISACON can
	help the transition to the VAX Integrated Architecture by
	generating the CDD description for your existing records.

	ISACON will generate a CDD entry for any record in your program.
	(It doesn't have to be only ISAM.)  You need only specify the
	Select clause associated with the record desired.  Naturally
	there are a few items to be wary of:

	A.)  Redefines clauses are oftentimes used to redefine
	computational and display items.  These features are dependent
	on the word size of the various machines and should be examined
	before trying them on another machine.

	B.)  The NAME for COBOL phrase for group level items is not
	allowed in the CDD.  ISACON does not generate it, so if you need
	the group name you cannot rely solely on the CDD.

	C.)  Sometimes it is useful to enter condition clauses (88
	levels) on group items.  This also is not allowed in the CDD.