021.7 F3LU. IUI
LATIN AMERICAN DATA BANK Users Manual
This manual is the documentation for the programs maintained by the Latin American Data Bank (LADB) at the University of Florida. It is divided into two sections: (1) the GENERAL Section, including the necessary Job Control Language (JCL) and other information general to all, or almost all, programs; and (2) the SERVICE Programs used by the LADB to service users.
Each program document is complete giving all the necessary information to run a job using an object program. Each document is broken down into a general Subsection, a user's guide, and a maintenance Subsection. The user will obtain a general idea of what each program will do from the general Subsection, and how to set up the cards to use the program from the user's guide. The maintenance Subsection is primarily for the LADB programmer to understand the logic of the program so that updates, modifications, etc. can be made to the source program.
All programs included in the initial issue of this manual (May, 1970) have been implemented and checked out on the UFCC IBM 360/65. The language of the source program and the original date of the program are Included with each document. The latest revision, if any, is noted by a number and date.
The original documentations included in this manual, along with the source program, are maintained by the LADB programmer. Any comments, questions, requests, etc. concerning either this manual or the associated programs should be directed to the Director, LADB or to the LADB programmer.
SECTION I GENERAL INFORMATION
General Document Deck Setup
LOADER ROUTINE: Date: January 1970
The General Deck setup for using the routine called 'LOADER' is Illustrated below, both for a source deck and an object deck. This routine is maintained by the Computer Center and is subject to changes periodically. Therefore, these setups should be verified by the Center Consultants before the first tine usage. Also, since most of the programs documented in this manual are In PL/1, the setups are given for this language.
SOURCE Deck OBJECT Deck
>.tape dp (//G0SYSINDD
Mg0.Object dp exec pl1cxm
Job Control Language (JCL)
JCL for Tape files.
Note: A lower case "b" in the following card formats stands for a blank column. There must be no other blanks in the card except at the end of a card. The last card ends with no punctuation, the others (cards to be continued) all end in a comma, Do not use any column past 71. Order is unimportant beyond the "DD" except that anything in parenthesis must be together.
The General Format Is:
//G0.file namebDDbUNIT=TAPEJ9/DSN=data set name,V0L-SERnumber, LABEL=(,(f$;y DISP-see below,'dCB(REC FM-see below, LRECL-see below,
The Second and Following Card Format Is:
//b whatever would not fit on the first card
Explaination of Terms.
File name. The file name is what the program knows the file as see the program document for the required file names. Most of the programs described here use the file name 'TAPE' for the input Tape File.
Unit=TAPE7 or TAPE9
This refers to a 7 track or a 9 track tape. The 360 has standard routines for handling both (independent of user control) but the user must specify one of the above names.
DSN = data set name.
Any combination of characters (alphanumeric) up to a maximum of 8, This is a file protection device; i.e. if DISP OLD (see below) Is specified, the system checks the DSN on the tape which must be the same as on the card or the system will terminate. If DISP NEW is specified, the system writes the DSN name on the tape before writing the records.
This is also a File Protection device* If LABEL (,SL) is specified, the VOL=SER must be the same on both the tape and the card or the system terminates. If LABEL=(,NL) is specified, there can be no Label on the tape or the system terminates. The V0LSER is up to 6 character alphanumeric combination with
with the first being alphabetic. The VolSer must be unioue for each tape in use
at any one time.
Multiple volume tape files are handled by enclosing the VOL-SER numbers in parenthesis and separating one from the next by a comma, example Vol-Ser-(X,Y,. .) where X,Y,. are each VOL'SER numbers.
This parameter specifies either STANDARD LABELS (SL) or NO LABEL (NL) The tape must have one or the other of these and the system cannot be fooled by specifying the wrong one. The statement within the parenthesis has the specific format 1,NL'or',SL', that is either NL or SL must be preceeded by a comma. The Default option of this parameter is SL, so if your tapes are Standard Labeled Tapes, this parameter may be omitted entirely.
There are 5 primary Keywords used in this parameter. They are 'OLD', 'NEW', 'KEEP', PASS, and MOD. If a tape is to be read only, OLD is used alone. This causes the DSN parameter to be verified by the system and includes the default option of KEEP which causes the tape to be rewound when the file is closed. The 'NEW* keyword is used when a tape is created. This causes the DSN to be written on the tape before any data. 'MOD' is used when you desire to add to an existing data set. This Keyword causes the tape (after checking VOL=SER= and DSN) to be positioned at the end of the data set and allows more data to be written on the tape. The 'KEEP* Keyword causes the tape to be rewound and unloaded after the job is completed. The 'PASS' Keyword bypasses the rewinding and unloading procedure and allows more than one job step to use the same tape. 'PASS* should not be used on the last job step using the tape. 'KEEP* and 'PASS' must occupy the second position of the Disp parameter. That is, if one of these are used, they should be preceded by one of 'OLD', 'NEW* or MOD, separated by a comma, and enclosed in parenthesis, example: DISP" (OLD,PASS).
This parameter contains several items all enclosed in parenthesis and separated from each other by commas. The order of the items is unimportant within the paranthesis. There are many subparameters for this parameter. The common ones follow:
Fixed Blocked records
Fixed Length records
Undefined length records
Variable length records
The Data bank tapes are all FB.
This is the length of a record. Usually 80 columns for data bank tapes. BLKS1ZE-
This is the total length of a physical block. It is the LRECL times the number of records per block. Example: a tape blocked 40 x 80 (most of the data bank tapes use this blocking factor) has a BLKSIZE of 3200.
This subparameter is optional but should be used for all input tspes. It causes a block to be skipped if the system cannot read the record. If ERQPT=SKP is not used, the job will terminate if the system cannot read the
DEN 1, TRTCH ET
These subparameters must be used for all 7 track tapes (Input or output).
General Document Tape Labeling
Placing Standard labels on a tape is s File protection device. It prevents doing a job using the wrong tape which results in incorrect data and/or could cause the Data Bank's tape file to be destroyed. If Standard Labels are specified (either explicitly or by default) the system checks the VOL=SER number and the DSN to see if they both match the ones stated on the tape JCL card for the job. If either of these parameters fail to match, the job terminates. The system cannot be fooled by specifying No Labels for a Standard Labeled tape. It checks to see if there are actually No Labels on the tape and the presence of a Standard Label will cause ter-
There are 2 ways of labeling a tape available at the UFCC. The first of these is a program written by the center programmers, called TPINIT, and is preferred. TPINIT requires only 3 cards (between the Password card and /* that signals the end of the job) and will write a Standard Label or No Label on the tape. This program must be used with all new tapes (NL or SL) so that the system can recognize that either Standard Labels or No Labels are present, the system will not accept a blank (New) tape without initialization.
The Deck setup for TPINIT is:
For a 9 track tape these parameters are optional, For A 7 Track Tape the following must be specified: UNIT,STAPE7,DEN="1,TRICH-ET
**SER is a 6 character serial number. Any combination of letters or numbers, with the first being Alphabetic. If SL is specified, the SER= number is written on the tape, if NL is specified, the SER" number is used to inform the operator which tape he is to mount, it should correspond in either case to the written label fixed to the tape reel.
OWNER* is any combination of 10 characters enclosed in quotes. It is used only if SL is specified.
The portion in the bracket may be repeated to label more tapes in the sane overall job. The program can accept muliple parameter in cards.
The second method of labeling tapes is useful only for placing Standard Labels on a tape. It is one of the programs contained in the IBM system support UTILITIES package. Its name is IEHINITT. This program requires several cards, (more than TPINIT) and hence is not preferrable to TPINIT. It is included here for completeness and for use if TPINIT is not availabe.
The Deck setup is:
//job name bJ0Bb( /'"'PASSWORD
//bEXECbPGM=IEHINITT //SYSPRINTbDDbSYSOUTA //TAPEbDDbDCBS5(DEN=2) ,UNIT=TAPE 9* //SYSINbDDb* CTAPEblNITTbSER- ,OWNER-*
SER Max 6 characters, First Character Alphabetic
OWNER Max 10 Characters enclosed in Quotes
If several tapes are to be labeled, repeat the cards indicated by the bracket changing the SER= no. and, if required, the owner name.
Either of these programs take only a very small amount of time, several tapes can be labeled in less than one minute.
NOTE: When using this program, note on your tape submittal card (center receptionist) that the operator should "reply '00'M'.
*9 Track Tape, For 7 Track the Parameters are (Den"*!, TRXCH*ET), Unit-TAPE 7
LANGUAGE ASSEMBLER_ PROGRAM: COPY
PROGRAMMER J. SEIPEL. UFCC ORIGINAL DATE Nov '69 CORE SIZE SMALL____ REVNO._DATE_
General: This program will copy records from one tape on another tape. It checks for the presence of headers and deletes these from the output tape. It also is useful in changing the blocking factor and in copying from 7 track to 9 track or vice versa. This program will handle only one input tape at a time.
JCL: Two cards are required
//GO. SYStFTlbPPb (Describe the input tape See JCL General
Section document) and //G0.SYSUT2bDDb (Describe the output tape)
There are no additional cards required for this program. The deck set up is:
i//g0.SYSUT2 DP //G0.SYSUT1 DP
J//LKEP.SYSIN DP *
[77 EXEC ALFXM \_
|/*PAS SWORD \ r~
This program can eliminate recorda that contain any specific combination of characters at any specific position on a record by modification In the source program. The necessary instructions to change this feature ara noted on the Source listing on file in the LADB.
Any other modifications should be referred to J. Seidel or the UFCC programmers.
SECTION II SERVICE PROGRAMS
Program Document LADB
Language PL/1 Program Sample Programmer L. Carstensen Original Date Nov. '69 Core Size Small Rev. no._Date
General: This program will read a tape and write every nth case out on either another tape or punch the record on a card. The user provides the number n, a code for the method of output, and number of card images per case.
Limitations: The program assumes that the input tape is composed of card images (i.e. 80 column records) the output is also in card images. Blocking factors are controlled by the JCL Statements. Rearrangement of Record Formats is not possible without programmer modifications. Record lengths differing from 80 columns also require programmer modification.
JCL: The JCL for this program is standard (see general section) except for //GO.0UTC file. Cards must be provided for:
(a.) //GO.TAPE (INPUT TAPE)
and either (b.) //GO.0UTT (use only if output on Tape)
or (c.) //GO.OUTCbDDbSYSOUTB,DCB-(RECFM-F,BLKSIZE-80) where b stands
for a blank column, no other blanks in the card (use only if output on cards)
NOTE: Items (b) and (c) are mutually exclusive, use only one of them.
OUTPUT: The program writes a Tape on cards as described above. In addition, it prints the following:
Number of Cases Read xxxx Number of cards per case xxxx
Number of Records written xxxx
Records sampled xxx percent
User's Guide: In addition to the above JCL, one data card is required by this program. Its Format, starting in card column one is:
N,C, Out 1
Where "N" is the number of cases to be skipped before selecting a case for output (sampled). "N" can be any number, but should not be less than 3 without the express permission of the Director, LADB*
Example: If a 10% saeple of a tape la desired, this means that one record in 10 is to be sampled, and N is 9, the number of cases skipped before one is sampled.
"C" is the number of card images per case. It is separated from "II" by a comma and "out" is separated from "C" by a comma. "Out" is a code for the method of output. "1" is used if a tape output is desired and "2" if card output is desired.
NOTE: The numbers "", "C", and the "Out" are separated by a single comma or by one blank column on the data card. The use of the comma is recommended.
Maintenance: The program first reads the card reader for the data card and converts "N", "C" and "Out" to Binary, Fixed point numbers.
It then reads the input file (called Tape) ignoring N*C records. The next records are then read and written out on the output file (called "OUTT" for tape output and "OUTC" for card output).
A count is kept of the total records read and total records written on the output file. The ratio of these is converted to percentage and written out on the printer, along with the total number of cases (N/C) read and the number written, at the end of the program.
The program uses the "based" variable option of PL/1 to work on the data while it is still in the Buffer area of the computer. This saves the time of moving the data into and out of the computer. The input variable is called "CARD" and the output variable ia called "RECOUT". Both are declared to be Character String variables.
Plan for possible modification:
a. Record lengths different from 80 columns. To change to a different record length simply change the length of the character string for "CARD" and "RECOUT". If the record lengths vary, the VARYING option can be added to these variables, and the specified length of the character string becomes the maximum it will have.
NOTE: A record length of greater than 80 columns will require extensive modification to the procedure "CARDO" (for card output). Provision will have to be made for more than one card per record and provision should be made, in this case, for a sequence number and a card number on the card output. Also, changes will be required in the JCL.
b. Rearrangment of card format:
This possible modification would require that the format of "CARD" reflect the input format and that of "RECOUT" reflect the desired output format. After the "LOCATE" Statement in either of the output routines, the "RECOUT"CARD"; a statement would have to be removed and replaced by statements for each variable desired in the output record. The "CHAR(80)" of both "CARD" and "RECOUT" would be removed and a "CHARQO" statement placed on each element of the structure.
Language: IBM System Support PROGRAM IERC0OO
Core Size: Variable Original Date Mar '70
This program is required so that the LADB Program "MARGIN" can be used. It is a member of IBM's SYSTEM SUPPORT Package. It will sort records on any number of variables in a specific order. Instructions are given only for the LADB use of this prograa. For any additional Instructions, the reader is referred to the UFCC.
The program requires a minimum of work files located on the SYSDA. The following calculations are required to determine the size of these files. The size is determined as the number of Cylinders or the Number of Tracks to be allocated to each work file. For Large Input Files, it is more economical to work in cylinders, if the Input file is small, the number of tracks should be calculated.
If tracks are used, simply replace the word "CYL" with "TRK" and the "#Cylinders" becomes the "#Tracks" on the program cards.
Any single work file must be located in on? contlnous space on the disk, or in System terminology, must bo contiguous. Because of Space limitations at the UfCC, A realistic auximm on any work file is about 25 cylinders. This helps to 4ftteraLns) how m.y wmk to mt 9 (leaesafe-ar tbe six sdnlana).
8 is the cumber of records on the taoo (Individual records, not blocks)
length of one Record
T Ll^S- Tot # tracks needed
If T is smaller than 120, determine the number of tracks per work file by dividing by 6.
T = Total # cylinders needed.
Divide by integer numbers starting with until an integer is found that gives a number between 10 & 25. This number is the # of cylinders per work file and the integer divisor is the number of work files needed.
The Deck setup for this job is;
// J0b fioooocv)
/^Password )200000'> //bEXECbPGM=IERC0OO, PARM='C0RE=(3OOOOO *J //S0RTLIBbDDbDSNsSYSI.S0RTLIB,DISP=SHR //SYS0UTbDDbSYS0UT=A //SYSDUMPbDDySYS0UT=A //S0RTlNbDDb(describe Input Tape) //S0RTOUTbDDb(describe Output Tape) //S0RTWKO1 //S0RTWKO2 //S0RTWKO3
//S0RTWKO4 P> bDDbl)NlT=SYSDA,SPACE=(Cyl, #cyl,,CONTIG)
bS0RTbFIELDS=(S,Y,Z,W, Repeat as required),Size=ES
Notes: 1. Core = 100000 for Small Core, 200000 for Medium Core, and 300000 for large core.
2. Input and Output Tape descriptions are the same as described in the General Document "JCL"
3. S0RTWK file cards are identical except for the number which is the number of work files needed calculated above.
4. The Sort Fields card and the END card must have a blank in
5. X = starting col of 1st variable involved in the sort. Y = Length (in card cols.) of the variable
Z CH for a character sort W = A for Assending Sequence
These four parameters are repeated (within the parenthesis) until all of the desired sort variables are described. The first set refers to the major sort variable and on down to the last set which refers to the minor variable.
ES = the approximate number of records on the tape preceded by the letter
Example: E135290 Means Estimated Number of Records 135290.
PROGRAMMER L. Carstenen
Core Size Variable
PROGRAM MARGIN Original Date Mar 70 Rev. No. Date
General: This program developes the marginal counts (i.e. Number of records matching each code of each marginal variable) for any number of marginal variables under any number of control variables. The CODES for either the control or marginal variables need not be known, the program prints the actual code found on the record. Multiple cards per case can be handled. The length of a single Control variable is limited to 10 characters, of a single Marginal variable to 5 characters. Counts for the first 999 levels of any Marginal variable will be printed and totaled. If more than 999 levels are present, a message is printed and any levels beyond the first 999 found are ignored. The program can skip any Number of records before starting.
1. This program requires that the records be sorted by the control variables on the tape. Refer to the document on the program "SORT" to do this.
2. Calculation of Core Size for Margin.
CS (No. of Marginal Variables X 13) + 13 if CS^lOO then CLASS-S
Co 5:400 break the job up into smaller chunks (i.e. use fewer
marginal variables per run and more runs)
3. This program produces a large volume of output, therefore it is setup to use off-line printing to reduce the cost. The output can be directed to the on-line printer (at a considerable increase in cost but a possible savings of a few hours to overnight in time) by changing the JCL card for the file "out" to read:
NOTE: This will produce only one copy of the output it will not give a permanent record on tape of the output. Hence, if another copy is desired later, the job must be rerun whereas if off-line printing was used, additional copies may be obtained by re-running the off-line tape on the 1401.
The JCL for the program is standard (see general section document). Cards must be provided for
(Describe Input Tape) (Describe OFF-Line Tape)
The first data card uses 11 80 columns for an alphassutsarie Title of tha job. Tha title rsist be enclosed In quotes and toe end quote Bust be followed fey a coma.
The second data card has the format
IXC, CTL, M&R, LBL, KgSSIP, where HOC la tha Number of Cards per Case
CTL Is the Huebar of Control Variables
mar is the Nusber of Marginal Variables
LBL is aero if Labels are inputted end any cucsber greater than earo if the built-in labels ere desired. lech number must be followed by a ecasaa, even t&e last one. : The use of tns built-la labels is discouraged*
^s de^e feay '''tkm R asstS) t&o t&a following &mti
CASS, LSI, CAES), 8, LOS, ....
Wiiare ) is the card no* that Contains the 1st Control variable
70S is the starting card col. for the first Control variable
LCT is the length (in card cols) of the first Control variable.
Repeat this forest until all the control variables and entered
and then, immediately, start with the Marginal variables until
they are ell entered. Do HOT split any one & between 2
cards (I.e. the lest character on e card is ). Separate
all numbers by a comma and place caeca after the last number.
The 4th data card (again may be more than one card) contains the variable labels. First the label for the first Control variable is entered, then the second and so on until the last Control variable, then start with the lstmariginel variable and or to tha last. All labels are9a eaxlsum of 20 characters and must be enclosed in quotes (Quote signs do not count In the 20 maximum) Also, if a quote sign is imbedded In the Label, it oust be entered as 2 consecutive quotes vith no space bst&een the quotes* This counts as one Space.
lFLORIDA"Sl will print out as FLORIDA'S and be considered as 9 characters long.
This continues to the case where you want the quote signs to be around the entire label: Example if you want the label *BOY OR GIRL1 to be printed including the quote signs, enter it as 1"BOY OR GIRL'" (The first & last quote signifies a literal and the two quotes together result in a printed single quote. This label is 13 characters long.)
Each label is separated from the next by a comma and the last one is followed by a coiraia.
No more data cards required
The detailed logic of the program is included as comments throughout the source program*
Generally th logic is this; After reading in the control values from the data cards, the program dyasric&lly cats up the storage required for this particular run.
If the Skip feature is used, the program reads the File 'Tape' and ignores N0SKIP records. It then writes a message on File '0UT* stating that there may be duplicates. This feature is used primarily if the first run of a job terminated prematurely. Then the job may be continued to completion by using the Skip feature and placing DISP=M0D on the File 'OUT'. It then reads 'TAPE' to get the first case and, using the SUBSTR Function of PL/1, determines the level of controls it has. Then it counts the Marginal variables and gets another record from 'TAPE'. If the control code equals the former one, the program adds the marginal counts to those it already has; if the control codes do not match, the program branches to the printing routine.
When the last record has been processed, the program prints the Marginal counts for the last set of control levels and then prints the total number of cases actually obtained from "TAPE" and stops.
The printing routine first calculates the total number of records it found within the set of controls and sorts the codes found for each marginal variable using the standard IBM system 360 collating sequence. As the tables are being printed out, the percentages are calculated and printed. The routine breaks the Marginals up into sets of 5 because the page width will only allow 5 Marginal sets to be printed across the page.
After all the data is printed, the storage is reinitialized and the program returns to count the next set of controls or branches to the end of the job if it is through.
Plan for possible Modification
a. Count Marginals for only selected control codes.
This would require that the desired control codes be known and inputted to the program. Storage would have to be provided and a routine for checking each record for a match to tha desired controls be Included. If such a match is found, the program could procede normally, if no match is found, the program would branch back to get the next record.
b. Output on cards or tape in card format.
This requires a new output routine that would set up the information in a card Format. JCL can determine where the output goes, either to cards or Tape. Provision has to be made to include soma sort of coding information on tha card to allow sorting and to print out a card Format showing where the information is located.
The Input routine should be the main Task end the output the attached Task. This would allow the nest Input structure to he filled wMle the former data Is being outputted.