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 :

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

RETURN to change  

                  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.


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.


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:


Enter Y if duplicate values are allowed for this key, otherwise enter N for no duplicates.


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.


Enter A if the values of this key are to be stored in ascending order, otherwise enter D for descending order.


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.

       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


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 '.


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.


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.


The level corresponds to the level number in a Cobol file definition (FD). This field is ignored in Basic programs


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.


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.


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.


The prompt is used by the utility programs to display a field and ask for an input or update.


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//.


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.


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.


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.