Return to Works Index
DSI Works - Describe
Describe is the common data dictionary utility for the DSI application
development system. It is used to maintain describe files which contain the
attributes of a file, including the key structure,and the field names within
the records. Describe files
are used by the precompiler, the design utilities, and the data access
and transfer utilities.
To create a describe file, type at the DCL prompt :
$ DSI DESCRIBE
The following screen will be displayed to enter the file attributes
and key structure of the file :
V4.17 Digital Synergy Inc - Describe Copyright 1997
Describe File __________________________________________________________
Default DB
Record Length
Org Record Format Attributes
Keys Dup Chg A/D Segs 1 2 3 4 5 6 7 8
Key 1
Key 2
Key 3
Key 4
Key 5
Key 6
Key 7
Key 8
Remarks
RETURN to change
Default:
Select F10=Exit
File Parameters
Describe File
Enter the name of the describe file. Do not include an extension,
as all describe files must have an extension of '.DSC'
If the describe file does not exist, then you will be prompted "Create
new describe file." Press RETURN to accept the default of Yes, or
enter N or F10 to go back to the database prompt.
Default DB
Enter the default name that SELECT will use when this describe file
is used to access a file. If a wildcard character (* or %) is used then
SELECT will show a table of all files that match the default name.
Record Length
Enter the record length. This is a minimum record length. If the
total of the fields in the record exceeds this then the actual record mapped
will be longer. There is no checking at this time for this condition.
Org
Enter the file organization. The valid organizations are sequential,
relative, indexed and virtual.
Record Format
Enter the record format. The valid formats are fixed, variable, stream
and VFC.
Attributes
Enter the record attributes. The valid attributes are CR, Fortan and Print.
Number of Keys
Enter the number of keys. If the file is not indexed, this question
will be skipped.
For each of the nine keys, you must enter the following information:
Dup
Enter Y if duplicate values are allowed for this key, otherwise enter
N for no duplicates.
Chg
Enter Y if changes are allowed for this key, otherwise enter N
for no changes. Note that this question is skipped for key 1 as RMS does not
allow changes on the primary key.
A/D
Enter A if the values of this key are to be stored in ascending order,
otherwise enter D for descending order.
Segs
Enter the number of segments that this key will be composed of.
1 thru 8
Enter the field sequence number of the key segment.
Function Keys
NEXT SCREEN from any prompt after the describe file
is entered will take you to
the next page.
PF1 will ask for an output file name defaulting to
SYS$OUTPUT. A listing of the
key structure and fields will then be generated. Terminals that can
will be switched to 132 column mode if the default is accepted and switched
back to 80 columns after the listing is finished.
Field Selection
If you are creating a new describe file, DESCRIBE will skip this screen
and go on to the field description screen.
Otherwise a screen similar to the following one is displayed. The
fields show on this screen are just an example.
DSI_DSC:CHANGE_TRANS
1 TRAN_KEY 1/32 STRING
2 TRAN_USERNAME 1/12 STRING
3 TRAN_DATE 13/8 STRING
4 CHANGE_KEY 21/10 STRING
5 SEQUENCE 31/2 STRING
6 CHANGE_NO 21/6 STRING
7 CHANGE_SUB_NO 27/3 STRING
8 CHANGE_SEQUENCE 30/1 STRING
9 DEPARTMENT_1 33/4 STRING
10 DEPARTMENT_2 37/4 STRING
11 DEPARTMENT_3 41/4 STRING
12 DEPARTMENT_4 45/4 STRING
13 DESCRIPTION 49/64 STRING
14 CENTER_1 113/4 STRING
15 CENTER_2 117/4 STRING
16 CENTER_3 121/4 STRING
17 CENTER_4 125/4 STRING
18 HOURS 129/4 SINGLE
19 CENTER_1_HOURS 133/4 SINGLE
Select Field Number ____
Default :
Select F10=Exit Next
If there are more than 19 fields in the database, the status bar at
the bottom of the screen will also show "Next Screen". Once Next Screen
is pressed the next 19 fields will be displayed and "Prev Screen" will be
added to the status bar. Pressing Prev Screen will move you back to
the previous set of fields.
If you enter a field number, you will go to the field definition screen.
Pressing F10 will return you to the first screen.
If you enter SELECT, you will be prompted for a query
string that will be used to match the field names. For example, entering
TRAN* would limit the display to
only fields that started with "TRAN", which in the above example
would be TRAN_KEY, TRAN_USERNAME and TRAN_DATE. To see all the fields again,
press SELECT and then RETURN.
This last feature is particularly useful when a record contains a
large number of fields.
Field Description
The next page is used to maintain the field information.
DSI Describe V4.24
Sequence 1 Dimensions
Low High
Type STRING Digits 0 Scale 0 1 0 0
Offset 1 Level 0
Length 32 2 0 0
Min Len 0
3 0 0
Variable TRAN_KEY
Mask INPUT FLAGS
Prompt TRAN_KEY Termination Date N
Heading TRAN_KEY Required N
Default View N UC only N
Initial Value Numeric only N
Condition Number 0 Numbers Only N
Verify min N Value Space Fill N
Verify max N Value Zero fill N
Verify list N List
RETURN to change _
Default :
F10=Exit PF1=List Next Prev F20=Rmrk Edit
Sequence
Each field is numbered sequentially. This numbering is used to tie
in the key information only. At the sequence prompt enter the sequence number
that you desire. An 'A' will automatically add new sequence number at the
end. The RIGHT_ARROW key will display the next higher sequence, the
LEFT ARROW will display
the next lower sequence, and the UP_ARROW will return
you to the key structure
page. If the sequence number does not exist you will be prompted
'Add '.
Type
Enter SELECT at the type field to see a list of data types. Note that
Basic does not support unsigned data types, so they are converted to signed
data types when used in a program. Also all date types are converted to
strings in a program.
Digits and Scale
For decimal, byte, word and long data the total number of digits and
the scale (the number of digits after the decimal point are asked for.
The number of digits can range from 1 to 31 and the scale can range from
0 to the number of digits. For byte, word and long, this information is only
used to generate Cobol file definitions for COMP data types.
Offset
The offset is the byte count to the first byte of the field. Therefore
records start at an offset of 1. It will default to the previous field offset
plus the previous field length.
Level
The level corresponds to the level number in a Cobol file definition
(FD). This field is ignored in Basic programs
Length
For each data type except string the length of the fields are automatically
filled in. String lengths are prompted for.
Min Len
Enter the minimum length that data in this field should contain.
Variable
The variable name can be any string up to 20 characters long. No
spaces are allowed and the string must be a valid variable name. There
are two ways a describe file can be used in a program. The first is by using
the "DSI MAP" directive. In this case the map name and an underscore are
appended to the front of the variable name. For example an variable name of
'NAME' with a map name of 'DATA' will result in an actual program name of
'DATA_NAME'. In this case the fact that NAME is a reserved word in Basic
does not cause a problem.
The second, and preferred method, is to use the "$DSI RECORD" directive.
This creates a Basic record statement and as such, the previous example would
produce the variable name DATA::NAME, which will not compile because NAME is
a reserved word.
Mask
The mask field is used to store an edit mask used to format the data
for display. This is used by the Java program generator and the SELECT.
Prompt
The prompt is used by the utility programs to display a field and
ask for an input or update.
Heading
The heading field is used by the report generator utility to create
column headings in reports.
Default View
The Default View is a flag field that can contain N, R or W. It is
used to load the initial view in SELECT. An N means this field is not
displayed, an R means this field is read and a W means this field can be
written to. See the documentation on SELECT for further information.
Condition Number
Conditions are tests that determine when a field is valid for a given
record. This is currently under development and the default should be taken.
Verify min and Value
If the Verify min question is set to Y, then the utility programs
will use the corresponding value specified as a minimum allowed value.
Verify max and Value
If the Verify max question is set to Y, then the utility programs
will use the corresponding value as a maximum allowed value.
Verify list and Value
If the Verify list question is set to Y, then the utility programs
will use the corresponding value as a verification list. If the first
character is 0 to 9, A to Z or a to z
then the values must be separated by commas. Any other first character
is taken as a delimiter (Note: the string must also end in the delimiter is
this case).
For example a value of Y,N or /Y/N/ both limit the field to either
Y or N. If the field is allowed to be blank, then in must be included in the
list as Y,,N or /Y/N//.
Dimensions
If the field is a single element (not an array) then put zero in the
first set of low and high dimensions. Up to a three dimensional array can be
specified by filling in the
low and high value for each dimension. If the describe file is to
be used with a Cobol program then the low dimension must be 1 and the high
dimension is the number of times the field occurs. This is a Cobol
restriction.
INPUT FLAGS
The input flags allow further specification of the data allowed in
the field. Note that
they are used only by the utility programs and the Java connection and
must be coded into Cobol or Basic programs.
Termination Date
Setting this flag causes all 9's to be stored, it the field is blank.
This is only valid for date data types.
Required
Setting this flag means that some data must be entered into the field.
UC Only
Setting this flag means that all lower case characters are to be converted
to uppercase before updating the field.
Numeric Only
Setting this flag limits the field to the characters 0 thru 9, plus,
minus and decimal point.
Numbers Only
Setting this flag limits the field to the characters 0 thru 9. This
corresponds to a Cobol PIC 9.
Space Fill
Setting this flag causes the contents of the field to be right justified
with leading spaces.
Zero Fill
Setting this flag causes the contents of the field to be right justified
with leading zeros.
