unisys ClearPath OS 2200 Display Processing System (DPS 2200) Form Design Programming Guide Level 6R5A February 2012 7831 2279 005
NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the products described in this document are set forth in such agreement. Unisys cannot accept any financial or other responsibility that may be the result of your use of the information in this document or software material, including direct, special, or consequential damages. You should be very careful to ensure that the use of this information and/or software material complies with the laws, rules, and regulations of the jurisdictions with respect to which it is used. The information contained herein is subject to change without notice. Revisions may be issued to advise of such changes and/or additions. Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data rights clauses. Unisys and ClearPath are registered trademarks of Unisys Corporation in the United States and other countries. All other brands and products referenced in this document are acknowledged to be the trademarks or registered trademarks of their respective holders.
Contents Section 1. DPS 2200 Overview 1.1. Documentation Updates... 1 1 1.2. Conventions Used in this Document... 1 2 1.3. DPS 2200 Description... 1 3 1.3.1. DPS 2200 Capabilities... 1 3 1.3.2. DPS 2200 Features... 1 4 1.4. DPS 2200 Components... 1 5 1.4.1. Form Design... 1 5 1.4.2. Interface to Applications Programs... 1 5 1.4.3. Additional Components... 1 6 1.5. Operating Environments... 1 7 1.6. Security... 1 7 Section 2. FORMGEN Processor Tutorial 2.1. Overview... 2 1 2.2. Learning to Use FORMGEN... 2 3 2.1.1. FORMGEN Guidelines... 2 3 2.1.2. Beginning the Tutorial... 2 4 2.1.3. Defining Form Attributes... 2 6 2.1.4. Defining Fields and Constants... 2 9 2.1.5. Changing Field Attributes... 2 14 2.1.6. Saving the Form... 2 17 2.1.7. Deleting Test Forms... 2 19 Section 3. FORMGEN Processor Reference 3.1. Calling FORMGEN... 3 1 3.2. Exiting FORMGEN... 3 3 3.3. Printing a Form... 3 4 3.4. Help Forms... 3 6 3.5. User Profile... 3 9 3.6. Error Handling and Messages... 3 14 3.7. Main Menu... 3 15 3.8. Form-Level Attributes Menus... 3 26 3.9. Image/Field Layout Functions... 3 34 3.9.1. Marking Capability... 3 35 3.9.2. Marking Character... 3 36 3.9.3. Marking Commands... 3 37 3.9.4. Marking Characters or Marking Commands in Text... 3 38 3.9.5. Marking Undo... 3 38 7831 2279 005 iii
Contents 3.9.6. Examples of Moves, Copies, and Deletes... 3 38 3.9.7. Repository Interface... 3 40 3.10. Repository Interface Menus... 3 42 3.10.1. Marked Area Menu... 3 43 3.10.2. Attributes List Menu... 3 45 3.10.3. Table Entries Menu... 3 46 3.10.4. Range Check Menu... 3 48 3.10.5. Table Check Menu... 3 49 3.11. Repeat Images Menu... 3 49 3.12. Image/Field Attributes Menu... 3 52 3.12.1. Image/Field Attribute Descriptions... 3 53 3.12.2. Rules for Specifying Attributes... 3 55 3.12.3. Alternate Attributes Menu... 3 57 3.13. Attribute Descriptions... 3 59 3.13.1. General Descriptions... 3 59 3.13.2. Attribute Choices for Specific Field Types... 3 70 3.14. Generate W/S Menu... 3 75 3.15. Print Form Menu... 3 79 Section 4. Form Language Definition Processor (FLDP) 4.1. Overview... 4 1 4.2. General Syntax Conventions... 4 1 4.3. Calling FLDP... 4 4 4.4. FLDP Positional Notation... 4 5 4.5. FLDP Definition Commands... 4 6 4.5.1. FORM Command... 4 7 4.5.2. TEMPLATE Command... 4 10 4.5.3. IMAGE Command... 4 11 4.5.4. FIELD Command... 4 15 4.6. Definition Statements... 4 19 4.6.1. BACKGROUND_ATTRIBUTES... 4 19 4.6.2. CHARACTER_ATTRIBUTES... 4 20 4.6.3. CHECKNUMBER_TEST... 4 20 4.6.4. CONVERSATION... 4 21 4.6.5. CURSOR... 4 21 4.6.6. DIMENSION... 4 22 4.6.7. EDIT_SYMBOL... 4 23 4.6.8. EMPHASIS... 4 24 4.6.9. FOREGROUND_ATTRIBUTES... 4 24 4.6.10. FUNCTION_KEYS... 4 25 4.6.11. GENERAL_EDIT... 4 26 4.6.12. HIGHLIGHT... 4 30 4.6.13. INPUT_ATTRIBUTES... 4 31 4.6.14. OUTPUT_ATTRIBUTES... 4 33 4.6.15. POSITION_IMAGE... 4 35 4.6.16. PREDEFINED_VALUE... 4 36 4.6.17. REPEAT_IMAGE... 4 38 4.6.18. SECURITY... 4 40 4.6.19. STORAGE... 4 42 iv 7831 2279 005
Contents 4.6.20. TAB... 4 44 4.6.21. TEST... 4 45 Section 5. Form Language Manipulation Utility (FLMU) 5.1. Overview... 5 1 5.2. Calling FLMU... 5 1 5.3. Examples Using FLMU... 5 5 Section 6. Definition Routines (D$DEF) 6.1. Overview... 6 1 6.1.1. Differences from Other Run-Time Routines... 6 1 6.1.2. Similarities to Other Run-Time Routines... 6 2 6.2. D$DEF Copy Procedures... 6 3 6.2.1. D$DEF Names Parameter... 6 4 6.2.2. D$DEF Attributes... 6 5 6.3. D$DEF Creating Routines... 6 16 6.3.1. D$DEFFLDCRE Function... 6 16 6.3.2. D$DEFFRMCRE Function... 6 20 6.3.3. D$DEFIMGCRE Function... 6 21 6.4. D$DEF Modifying Routines... 6 24 6.4.1. D$DEFFLDMOD Function... 6 25 6.4.2. D$DEFFRMMOD Function... 6 26 6.4.3. D$DEFIMGMOD Function... 6 27 6.5. D$DEF Retrieving Routines... 6 28 6.5.1. D$DEFFLDRET Function... 6 29 6.5.2. D$DEFFRMRET Function... 6 30 6.5.3. D$DEFIMGRET Function... 6 31 6.5.4. D$DEFNAMRET Function... 6 32 6.6. D$DEF Deleting Routines... 6 35 6.6.1. D$DEFFLDDEL Function... 6 35 6.6.2. D$DEFFRMDEL Function... 6 36 6.6.3. D$DEFIMGDEL Function... 6 37 6.7. D$DEF Form Library Access Routines... 6 38 6.7.1. D$DEF File Access Authorities... 6 39 6.7.2. D$DEFERASE Function... 6 39 6.7.3. D$DEFLOAD Function... 6 40 6.7.4. D$DEFSAVE Function... 6 42 6.8. Miscellaneous Routines... 6 44 6.8.1. D$DEFPRINT Function... 6 44 6.8.2. D$DEFGENWS Function... 6 46 Appendix A. FORMGEN Messages A.1. Acknowledge Messages That Apply to All Functions... A 1 A.2. Error Messages That Apply to All Functions... A 2 A.3. Termination Acknowledge Messages... A 2 A.4. Termination Error Messages... A 3 A.5. Help Error Messages... A 4 7831 2279 005 v
Contents A.6. Image/Field Attributes (A) Acknowledge Message... A 5 A.7. Image/Field Attributes (A) Error Messages... A 5 A.8. Form-Level Attributes (F) Acknowledge Message... A 16 A.9. Form-Level Attributes (F) Error Messages... A 17 A.10. Layout (L) Acknowledge Messages... A 20 A.11. Layout (L) Error Messages... A 20 A.12. Main Menu (M) Acknowledge Messages... A 25 A.13. Main Menu (M) Error Messages... A 27 A.14. Print Menu (P) Acknowledge Messages... A 33 A.15. Print Menu (P) Error Messages... A 33 A.16. Repeat Attributes Menu (R) Acknowledge Message... A 37 A.17. Repeat Attributes Menu (R) Error Messages... A 37 A.18. Profile (U) Acknowledge Message... A 42 A.19. Profile (U) Error Messages... A 42 A.20. Repository Interface Acknowledge Messages... A 46 A.21. Repository Interface Error Messages... A 47 A.22. Initial Values Menu (V) Acknowledge Message... A 49 A.23. Initial Values Menu (V) Error Messages... A 49 A.24. Generate Working Storage Menu (W) Acknowledge Messages... A 50 A.25. Generate Working Storage Menu (W) Error Messages... A 50 A.26. Execute Menu (X) Error Messages... A 57 A.27. Internal Error Messages... A 57 A.28. Error Messages Caused by Invalid Attribute Identifiers and Values... A 68 Appendix B. FDLP Messages Appendix C. D$DEF Messages C.1. Error Messages... C 1 C.2. Warning Messages... C 9 Appendix D. Sample Program Using D$DEF Routines Appendix E. Sample Form Definition Using FLDP Processor Glossary... 1 Index... 1 vi 7831 2279 005
Figures 2 1. Defining a Form... 2 2 7831 2279 005 vii
Figures viii 7831 2279 005
Tables 3 1. Device Type Mnemonics... 3 2 3 2. Image/Field Types... 3 60 3 3. System-Supplied Field Types Description... 3 61 3 4. Attribute Descriptions... 3 64 3 5. Mutually Exclusive Attributes... 3 68 3 6. Attribute Choices for Field Types A and X... 3 70 3 7. Attribute Choices for Field Type B... 3 71 3 8. Attribute Choices for Field Types C, I, and N... 3 72 3 9. Attribute Choices for Field Types R and D... 3 73 3 10. Attribute Choices for ON/OFF Images... 3 74 4 1. Valid Form Level Definition Statements for FORM Command... 4 9 4 2. Valid Image_Level Statements for Nonrepeating Images... 4 14 4 3. Valid Image_Level Statements for Repeating Images... 4 15 4 4. Valid Field-Level Statements for Fields (Nonconstant, Nonsystem- Applied)... 4 18 4 5. Valid Field-Level Statements for System-Supplied Fields... 4 19 6 1. Form Level Attributes, Values, and Defaults... 6 6 6 2. Image Level Attributes, Values, and Defaults (Repeats and ON/OFFs)... 6 8 6 3. Field Level Attributes, Values, and Defaults... 6 11 7831 2279 005 ix
Tables x 7831 2279 005
Section 1 DPS 2200 Overview The OS 2200 Display Processing System (DPS 2200) enables programmers to define forms (screens) and incorporate them into application programs. It separates the development and use of forms from other tasks in an application program. This guide describes DPS 2200 and how to use it. It is intended primarily for applications programmers who create new forms and modify existing forms. DPS 2200 provides several processors and routines that allow you to create and modify forms in different ways. This guide explains The FORMGEN processor, which allows you to create and modify forms interactively. The Form Language Definition Processor (FLDP), which allows you to create and modify forms in batch mode or in a demand environment. The Form Language Manipulation Utility Processor (FLMU), which allows you to modify, convert, and secure the DPS 2200 form definitions in the form library The D$DEF routines, which allow you to create and modify temporary forms and dynamically define forms during program execution. 1.1. Documentation Updates This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) 18848031. To obtain a copy of the PLE, contact your service representative or access the current PLE from the product support Web site: http://www.support.unisys.com/all/ple/18848031 Note: If you are not logged into the product support site, you will be asked to do so. 7831 2279 005 1 1
DPS 2200 Overview 1.2. Conventions Used in this Document Syntax Conventions This manual uses the following conventions for syntax: Command names, system variable names, and system function names are shown in uppercase letters. User-supplied variable information such as command options, system variable values, and system function values are shown in lowercase italic letters. Naming Conventions The following naming conventions apply to form library names, form names, image names, field names, repeat index names, and cursor field names. Form library This name can be any combination of ASCII letters, digits, the $ symbol, and the minus sign (-). Form Image, field, index, and cursor names This name can be any combination of ASCII letters and digits. The first character must be an ASCII letter, a digit, or an 8-bit character (octal codes 0246 to 0337). All other characters can be any combination of ASCII letters, digits, the minus sign (-), and 8- bit characters (octal codes 0246 to 0337). Trailing spaces are permitted. Embedded spaces are not allowed. The last character cannot be an ASCII minus sign (-). At least one character must be an ASCII letter of 8-bit characters (octal codes 0246 to 0337). Screen Conventions The following screen conventions apply when using DPS 2200: Use the tab key to position the cursor to a field in which you want to enter new data or change existing data. Usually, the fields enclosed in brackets ([ ]) and underscores (_) indicate the number of allowable characters. Output-only (OO) data is displayed in protected fields. You cannot change this data. 1 2 7831 2279 005
DPS 2200 Overview 1.3. DPS 2200 Description DPS 2200 is an application development tool that simplifies the development of interactive full-screen applications. DPS 2200 enables you to define forms (screens) and incorporate them into your application programs. It separates the development and use of forms from other tasks in an application program. 1.3.1. DPS 2200 Capabilities DPS 2200 enables you to Reduce program development time for programs requiring full-screen interaction with different types of terminals (device independence) Reduce program development time for transaction programs Reduce errors (DPS 2200 automatically handles input errors) Standardize user interface using the repository Provide easy definition, update, and review of forms Provide form and field security without special security codes in your program Dynamically control field display attributes like intensity, highlight, emphasis, font, and color Refresh a form after accidental destruction Store statistical and trace information about terminals in the TIP environment Define initial default values for fields during form definition Perform run-time validation of user input 7831 2279 005 1 3
DPS 2200 Overview 1.3.2. DPS 2200 Features DPS 2200 provides the following features: Stores the data defining a form in a form library Generates working storage in the demand environment or batch mode. The output element is compatible with ASCII COBOL, UCS COBOL, ASCII FORTRAN, UCS FORTRAN, or UCS C Completes input/output (I/O) editing within the run-time handler. It removes I/O buffers from a program and transfers only dynamic information to a program. The user program receives and supplies data transferred to and from the form in internal format (for example, numeric computational) Generates internal error messages and displays them on a specified message line when logical errors occur in input data Supports 7-bit and 8-bit character sets Generates up to 10,000 pages of output Provides standard transaction/demand programs to handle LOGON/LOGOFF sequences and to control terminal test modes that enable or disable displaying data fields Supports the integrated recovery environment (IRE) Generates working storage in the repository (UCS COBOL and UCS C) for a form if DPS 2200 is configured to use the repository. See Volumes 1 and 2 of the UCS COBOL Programming Reference Manual and Volumes 1 and 2 of the UCS C Programming Reference Manual for a description of the statements you can use to access this information Provides the capability for an application program to lock the keyboard while an output message is being sent to a terminal. This capability is useful when an application program is busy and cannot receive input from the keyboard until it completes the current operation. It also allows an applications program to send status messages and perform other functions Provides an extended security environment that ensures that sensitive data is protected Provides the capability for run-time validation of input data. At user program execution time, data entered in an I/O field is compared to either a user-defined table of values or a user-defined range Provides the capability to transliterate the literal text and initial field values from the CCS used during screen definition, into the CCS in use at run-time 1 4 7831 2279 005
DPS 2200 Overview 1.4. DPS 2200 Components This subsection describes the DPS 2200 components that enable you to define forms and incorporate them into application programs and to manage your DPS 2200 system. 1.4.1. Form Design The following DPS 2200 components enable you to create and edit forms: FORMGEN processor The FORMGEN processor is a full-screen interactive component of DPS 2200 enabling you to define, modify, and delete forms. FORMGEN includes learning aids and extensive online help screens. FLDP FLDP is the batch mode equivalent of the FORMGEN processor. You define forms with a series of commands. FLDP is for experienced programmers. D$DEF routines The D$DEF routines enable you to dynamically define and edit forms within an application program. D$DEF routines are for experienced programmers. They require knowledge of languages supported by DPS 2200 (such as COBOL) and of other OS 2200 software products. FLMU FLMU enables you to modify, convert, and secure the DPS 2200 form definitions in the form library, and generate working storage. 1.4.2. Interface to Applications Programs DPS 2200 provides an interface between form definitions and application programs and run-time routines. The DPS 2200 run-time routines operate in the following environments: Demand (remote symbiont interface [RSI]) Transaction Processing/Message Control Bank (TIP/MCB) and Integrated Recovery Version II or III Transaction Processing/communications buffer (TIP/COMPOOL) After you define your form with the FORMGEN processor, FLDP, or the D$DEF routines, you must transfer it to an output file in either COBOL, FORTRAN, or C, depending on your application. This is called generating working storage. The application program manipulates the variables and communicates with the DPS 2200 run-time system collected with the program through a language-dependent interface routine. Interface routines are available for COBOL, FORTRAN, MASM, and C. 7831 2279 005 1 5
DPS 2200 Overview The run-time routines communicate with an application program and its environment through a comprehensive set of procedures or functions. The application program uses DPS 2200 run-time routines, working storage, and parameter definitions to accomplish interactive tasks. The run-time routines control the terminal through OS 2200 by displaying the form named in the application along with any output variables defined in working storage. Then the run-time system receives the input variables, validates them, and stores them correctly in working storage. A set of error handling routines is available to help you resolve problems with the input. 1.4.3. Additional Components The following is a list of additional components that enable you to manage, monitor, and control DPS 2200 and your applications. DPSIF DPSPW HELPER LISTER LOGON LOGOFF PAGING REFRESH STATS TCLEAR TMODE TTYPE The File Initialization Processor initializes DPS 2200 system files. The User-id/Password processor generates and maintains information about authorized users of a DPS 2200 system. This component produces information at your terminal about your DPS 2200 configuration. The LISTER processor produces a list of all user records in the password file as well as a list of all forms in the form library. The LOGON processor starts a DPS 2200 session. This processor is optional. The LOGOFF processor removes the user-id/password and its associated security information from the terminal file record. Use it to end a DPS 2200 session. This component retrieves forms stored by DPS 2200 paging functions and displays them on a terminal one at a time. The REF processor redisplays an accidentally destroyed form. This component produces information at your terminal about the use of DPS 2200 in a TIP environment. This component enables you to clear another person's terminal record or your own terminal record. TCLEAR is used only by site administrators. This component turns the test mode on and off for an executing terminal. Test mode causes a terminal to display information that is not normally displayed. This component enables you to specify the terminal type or to ask DPS 2200 what type is currently specified for the terminal. 1 6 7831 2279 005
DPS 2200 Overview 1.5. Operating Environments You can configure DPS 2200 for a demand (remote symbiont interface [RSI]) environment or for both a demand and TIP environment. An experienced programmer usually performs the configuration. With the TIP and demand configurations, you can execute TIP transactions in a demand environment without recompilation or recollection if they were appropriately coded. Also, you can test TIP transactions in a demand environment using normal programming aids, such as the FLIT processor, PostMortem Dump (PMD) processor, and Programmers Advanced Debugging System (PADS). Programs executed in either a TIP or a demand environment must run on a terminal with the same size screen as the terminal configured with DPS 2200. Currently, DPS 2200 supports terminals with a screen size of 24 rows and 80 columns only. This restriction applies only for programs executed in the TIP and demand environments. Programs run in batch mode can execute from any device. 1.6. Security DPS 2200 enables you to generate forms that display only those parts corresponding to the security level of the logged-on user-id. Every user-id has security levels assigned to it. There are two levels of security: Form security defines which forms a particular user-id can access Field security defines which fields a particular user-id can receive Note: The application program should always supply the output data for all fields. DPS 2200 determines whether to display the data. Therefore, you can use the same application program for different displays without being concerned with the kind of display or the current security level. You do not need any code in the program to handle security checking. Form level security returns an error code that the program must accept. You must attach a security level to each form and individual field. DPS 2200 compares these levels with your active security level and takes the appropriate action to ensure that you receive only the proper data. 7831 2279 005 1 7
DPS 2200 Overview You can define additional levels of security when you define a form. Define forms and their fields as having either soft or hard security, as follows: Soft security A user-id must have a security level equal to or greater than the form or field security level to open the form or receive the fields. Hard security A user-id must have the same security level as the form or field to use the form or fields. Anyone can use a form or field with the lowest security level, which is 1. DPS 2200 always displays a field with this security level. If you do not sign on to DPS 2200 using the LOGON processor, the run-time initialization function of DPS 2200 assigns the lowest security level to you. In demand and batch programs, the DPS 2200 security system links to the Exec security system. Use the Exec user-id, if any, in these programs. In the TIP environment, DPS 2200 uses its own LOGON transaction to link user-ids to terminals, unless TIP session control is configured in the Exec and MCB is in use. TIP session control is available only in the TIP/MCB environment and identifies a TIP user to the transaction system. When it is configured, TIP session control solicits a valid user-id/password similar to demand mode. DPS 2200 performs an ER INFO$ to retrieve the user-id that was in effect when you signed on to the system. It is no longer necessary to execute the LOGON processor to start a TIP session and to set up the security for a specific user-id. This is now done automatically by DPS 2200. However, you can still use the LOGON processor. 1 8 7831 2279 005
Section 2 FORMGEN Processor Tutorial This section introduces the FORMGEN processor and contains a step-by-step procedure that shows how to create a simple form. This tutorial shows some of the capabilities of the FORMGEN processor and provides enough information to get started. See Section 3 for reference information and a more detailed description of the FORMGEN processor. 2.1. Overview The DPS 2200 FORMGEN processor enables you to create and change forms to meet the unique requirements at your site. FORMGEN combines the default attributes that satisfy your requirements with the attributes that you change and the data you enter to produce a form. As you define a form, FORMGEN temporarily stores the data in a workspace in main storage. When you finish defining a form, you must instruct FORMGEN to permanently store a copy of your form in mass storage. This tutorial uses the following definitions for the terms you and end user: In the following discussion, you refers to applications programmers who use FORMGEN to create and modify forms unique to a specific task. They provide the forms needed for a business providing daily service to customers. An end user is a data entry person who uses the forms that you create and modify. For example, an end user might work at a reservations counter and use your form while selling tickets to a ball game or reserving seats for a concert. When end users use your form, they merely tab to the applicable fields you defined and enter a customer's name, address, phone number, requested seat number, and so forth. 7831 2279 005 2 1
FORMGEN Processor Tutorial Figure 2 1 shows the steps that FORMGEN performs while you define a form, generate working storage for the application programs, and print a listing. It shows the following sequence of events: While defining a form with default attributes or entering new attributes, FORMGEN stores the data in a temporary storage area called a work space. When you finish defining the form, instruct FORMGEN to store the data in permanent storage. Also, instruct FORMGEN to generate working storage for the form. This is the data that an application program reads when it uses the form. If you want a hard copy, instruct FORMGEN to transfer the data to a print file and you can generate the listing from that file. Figure 2 1. Defining a Form 2 2 7831 2279 005
FORMGEN Processor Tutorial 2.2. Learning to Use FORMGEN The following example shows you how to use some of the FORMGEN functions. By performing this step-by-step process (WALK-THRU mode), you can see the results of the commands and data you enter. You will be instructed to enter specific commands and data. Screens displaying the menus and forms will show the results of these actions. A brief description of the commands is included. See Section 3 for more detailed information. 2.1.1. FORMGEN Guidelines The underlined areas in the figures represent fields in the form. You can enter data in these fields in lowercase or uppercase letters. Some parameters have two fields (for example, auto save count). The first field contains data entered with the FORMGEN processor. The second field contains the default value for the first field. You can request user help by entering the help character in a single field or multiple fields and pressing XMIT. FORMGEN displays the help form for the first field in which you requested help. Note: You cannot change data on a menu and request help from that menu with the same transmit sequence. Help requests are processed before any other information on the menu. When you finish with the help for a field, you can request help for the next field by entering the letter e in the help functions selection field at the bottom of the help form and pressing XMIT. Most help forms contain narrative descriptions while a few list all possible values for a field. See Section 3 for additional information about help. Return to the form from which you requested help by either pressing F4 (function key 4) or by entering the letter r in the help functions selection field at the bottom of the help form and pressing XMIT. When FORMGEN displays the form from which you requested help, the cursor is positioned over the first help character. 7831 2279 005 2 3
FORMGEN Processor Tutorial 2.1.2. Beginning the Tutorial Step 1 Call FORMGEN and display the Main Menu by entering @FORMGN <press XMIT> The Main Menu looks as follows. Device: UTS20 DPS 2200 FORMGEN PROCESSOR Main Menu DPS Level: 6R4 User Level: 6R4 Library command new (DELETE (workspace), ERASE, NEW, OLD, REPLACE, SAVE) Form name example <FORM> Form number 0 <0> File type F <F> (F-Formlib, O-Omnibus) Form library SCREEN$FILE Omnibus name (qual*file.elt/vs) Auto save count 1 <1> (0-99) Expertise level 1 <2> (1, 2, 3) ------------------------------------------------------------------------------ A = Image/field attributes M = Main menu (F1) V = Initial values D = Repository interface O = Exit with omit (F6) W = Working storage E = Exit with replace (F5) P = Print form X = Execute (display) F = Form-level attributes R = Repeat images L = Image/field layout U = User profile? = Help (any field) Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP 2 4 7831 2279 005
FORMGEN Processor Tutorial Step 2 Enter the data for the following main menu fields. Library command Enter NEW in the Library command field (this is a three-character field). This command creates a new form. Form name Enter EXAMPLE in the Form name field (this is an eight-character field). This assigns the name EXAMPLE to the new form. The default name is based on the value in your user profile. Form number The form number must be unique to this form. It identifies the form you are creating. The default value is 0. If you use 0, FORMGEN uses the next available form number. If you are not sure whether you should use the default value, ask your supervisor for a form number to use during this exercise. File type Selects the type of file you want to read data from or which you want to write data to. The default file type is based on the value in your user profile. Form library The name of the file where FORMGEN stores the form you are creating. A form library is like a book library. The default file name is based on the value in your user profile. Your form library file name may differ from the one in the figure (SCREEN$FILE) because your file name is determined when your site administrator configures the system. Auto save count Auto save count instructs FORMGEN to save your form definition in an auto-recovery file after a specified number of updates. This capability lets you recover your form if the system fails while you are working on it. The default auto save count is based on the value in your user profile. Expertise level Enter 1 in the Expertise level field (this is a one-character field). This reflects your current level of experience with FORMGEN. This example can only be performed in WALK-THRU mode, which is only available in expertise level 1. The default value is based on the value in your user profile. 7831 2279 005 2 5
FORMGEN Processor Tutorial Step 3 Press XMIT. The cursor can be in any position on the screen because the entire form is always read. FORMGEN displays the following message on line 24: *** NEW FUNCTION PERFORMED. ENTER FKEY 4 FOR WALK-THRU MODE *** Step 4 Press F4. FORMGEN displays an introduction to the WALK-THRU mode and instructions about the use of F4 and XMIT. 2.1.3. Defining Form Attributes Press either F4 or XMIT. FORMGEN displays page 1 of the Form-Level Attributes menu. The Form-Level Attributes menu lets you define the display attributes of your form. For example, you can define components such as form height and function keys. Page 1 looks as follows. EXAMPLE 0 DPS 2200 FORMGEN PROCESSOR Form-level (1 of 3) Final cursor field name <1st I/O field> (Any I/O field) Security level 1 <1> (1-63) Security type S <S> (H-Hard, S-Soft) Form height 1 <last line of text or images> (1-24) Generate prefix Y <Y> (N-No, Y-Yes) Initial conversation mode N <N> (N-No, Y-Yes) Check number validate Test mode Y <Y> (N-No, Y-Yes) N <N> (N-No, Y-Yes) Function keys <N> (A-All, N-None, 1-36) N Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP All fields on page 1 have default values as shown. Do not change any of these values. See Section 3 for a complete description of all the fields on page 1. 2 6 7831 2279 005
FORMGEN Processor Tutorial The final cursor field name is blank because you have not yet defined any fields. It defaults to the first I/O field in the form. Step 5 Press XMIT. FORMGEN displays page 2 of the Form-Level Attributes menu. If you changed page 1 before transmitting, FORMGEN displays the following message on line 24 to indicate that all values on page 1 were accepted: *** FORM-LEVEL ATTRIBUTES UPDATED *** Page 2 looks as follows. EXAMPLE 0 DPS 2200 FORMGEN PROCESSOR Form-level (2 of 3) Background color E <E> (B-Blue, C-Cyan, E-Ebony, G-Green, M-Magenta, R-Red, W-White, Y-Yellow) Foreground: Color W <W> (B-Blue, C-Cyan, E-Ebony, G-Green, M-Magenta, R-Red, W-White, Y-Yellow) Intensity N <N> (H-High, L-Low, N-Normal, S-Suppressed) Highlight N <N> (B-Blink, N-None, R-Reverse) Emphasis N <N> (L-Leftcolumn, N-Normal, S-Strike, U-Underscore) Font/Character set N <N> (N-Normal, 1-Alt1) Control characters N <N> (B-Blink, N-None) I18N CCS Number 35 <35> (O-No Transliteration, Greater Than O-CCS) Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP All fields on page 2 have default values as shown. Do not change any of these values. See Section 3 for a complete description of all the fields on page 2. 7831 2279 005 2 7
FORMGEN Processor Tutorial Step 6 Press XMIT. FORMGEN displays page 3 of the Form Level Attributes menu. If you changed page 2 before transmitting, FORMGEN displays the following message on line 24 to indicate that all values on page 2 were accepted: *** FORM-LEVEL ATTRIBUTES UPDATED *** Page 3 looks as follows. EXAMPLE 0 DPS 2200 FORMGEN PROCESSOR Form-level (3 of 3) Enter special characters: Start image character [ <[> Stop image character ] <]> Field character Alternate field character SOE character _ <_> Thousands delimiter, <,> Decimal point symbol. <.> Marking character No default No default No default Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP All fields on page 3 except the Alternate field character, SOE (start-of-entry) character, and Marking character have default values as shown. Do not change any of these values. See Section 3 for a complete description of all the fields on page 3. Step 7 Press XMIT. FORMGEN displays page 1 of the Form-Level Attributes menu. If you changed page 3 before transmitting, FORMGEN displays the following message on line 24 to indicate that all values on page 3 were accepted: *** FORM-LEVEL ATTRIBUTES UPDATED *** 2 8 7831 2279 005
FORMGEN Processor Tutorial 2.1.4. Defining Fields and Constants Step 8 Press F4. FORMGEN displays a form containing information about the Image/field layout form. This is where you actually lay out the constants and fields of your form. You can rearrange fields and change information until you are satisfied with your form. When you create a new form, you have access to all positions on the form. This example creates a simple form containing four fields and the text constants identifying each field. FORMGEN defines a field as those positions available for entering information. The text constant is not part of the field. Underscores describe the field size by indicating the number of positions available for entering information. In this example, the first field has 24 underscores. This means that you can enter a maximum of 24 characters in the first field. After reading the information, press XMIT. Because you are creating a new form, the form is blank. Enter the following number of underscores in each field: NAME 24 CITY 16 STATE 6 EDUCATION 24 Enter the following text constants and fields in the following locations. Starting Location row 1 column 1 row 3 column 1 row 5 column 1 row 7 column 1 Text Constant Field NAME: CITY: STATE: EDUCATION: When you finish entering this data, press XMIT. 7831 2279 005 2 9
FORMGEN Processor Tutorial Step 9 FORMGEN displays a message momentarily on line 24 when it redisplays the form with no changes. The form looks as follows. NAME: CITY: STATE: EDUCATION: If the form is okay, press XMIT a second time and go to step 10. If the form is not okay, change it. To change an existing form, do the following: Type over existing data. Delete existing data. Add new data in any position on the form. When you finish making changes, press XMIT or F4. When the form is okay, press XMIT a second time and go to step 10. 2 10 7831 2279 005
FORMGEN Processor Tutorial Step 10 FORMGEN displays the Repeat Images menu with the following message on line 24: *** IMAGE AND FIELD LAYOUT UPDATED *** : * AUTO * The Repeat Images menu looks as follows. EXAMPLE 0 DPS 2200 FORMGEN PROCESSOR Repeat Images 1AME: 2 3ITY: 4 5TATE: 6 7DUCATION: 8 9 0 1 2 12345678901234567890123456789012345678901234567890123456789012345678901234567890 0 1 2 3 4 5 6 7 8 --------------------------------------------------- STARTING LINE 1 (n,+n,-n) CHG TYPE INDEX NAME DIR ROW S-COL E-COL COUNT SPACING LINES/UNIT LITERALS Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): *** IMAGE AND FIELD LAYOUT UPDATED *** : * AUTO * On this menu, the line number overwrites the first letter of each text constant. This line number states where your data is located. This menu lets you repeat (duplicate) fields in both vertical and horizontal directions. The top portion of the menu shows the first 12 lines of your form. The bottom portion of the menu is an area for entering applicable information about your repeat operations. This information controls the duplication of the fields. This example shows how to repeat the EDUCATION field. See Section 3 for more information about the Repeat Images menu. 7831 2279 005 2 11
FORMGEN Processor Tutorial Step 11 Enter the following data: The letter i in the CHG TYPE field informs FORMGEN that you are inserting a repeat. The name index4 in the INDEX NAME field uniquely identifies the field you want to repeat. You can either enter a name or let FORMGEN assign a default name. The letter d in the DIR field specifies repeating (duplicating) the field in the vertical direction (down). The number 7 in the ROW field specifies the number of the first line repeated. The letter y in the LITERALS field specifies repeating the literal values (text constant). The default value is n. However, in your example, you want the literal values repeated. FORMGEN assigns default values for fields in which you did not enter data. EXAMPLE 0 DPS 2200 FORMGEN PROCESSOR Repeat Images 1AME: 2 3ITY: 4 5TATE: 6 7DUCATION: 8 9 0 1 2 12345678901234567890123456789012345678901234567890123456789012345678901234567890 0 1 2 3 4 5 6 7 8 --------------------------------------------------- STARTING LINE 1 (n,+n,-n) CHG TYPE INDEX NAME DIR ROW S-COL E-COL COUNT SPACING LINES/UNIT LITERALS i index4 d 7 y Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): *** IMAGE AND FIELD LAYOUT UPDATED *** : * AUTO * 2 12 7831 2279 005
FORMGEN Processor Tutorial When you finish entering data, press XMIT. FORMGEN redisplays the Repeat Images menu, with the education field repeated on line 8. In addition, FORMGEN inserts default values in the empty fields and displays the values in uppercase. FORMGEN also displays the following message on line 24 to indicate that the images were successfully updated: *** REPEAT IMAGES UPDATED *** :AUTO * The updated Repeat Images menu looks as follows. EXAMPLE 0 DPS 2200 FORMGEN PROCESSOR Repeat Images 1AME: 2 3ITY: 4 5TATE: 6 7DUCATION: 8DUCATION: 9 0 1 2 12345678901234567890123456789012345678901234567890123456789012345678901234567890 0 1 2 3 4 5 6 7 8 --------------------------------------------------- STARTING LINE 1 (n,+n,-n) CHG TYPE INDEX NAME DIR ROW S-COL E-COL COUNT SPACING LINES/UNIT LITERALS N INDEX4 D 7_ 1_ 80 2_ 0_ 1_ Y Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): *** REPEAT IMAGES UPDATED *** : * AUTO * 7831 2279 005 2 13
FORMGEN Processor Tutorial 2.1.5. Changing Field Attributes Step 12 Press F4. FORMGEN displays the Image/Field Attributes menu. The Image/Field Attributes menu looks as follows. EXAMPLE 0 NAME: 1 CITY: 2 STATE: 3 EDUCATION: 4 EDUCATION: 4 DPS 2200 FORMGEN PROCESSOR Image/Field Attributes ------------------- STARTING LINE 1 (n,+n,-n) STARTING FIELD 1 (n,+n,-n) IMAGE NAME TYPE ATTRIBUTES ( ^ = alternate select menu) 1 IMAGE1 X 2 IMAGE2 X 3 IMAGE3 X 4 IMAGE4 X Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP This menu lets you change the name, type, and attributes of each field. The top portion of the menu shows your fields. The bottom portion shows the image name, type, and attributes for your fields. The menu contains the default names (IMAGE1, IMAGE2, and so forth), field type (X), and attributes (default values only; none are displayed). (See Section 3 for a complete description of the Image Attributes menu.) Enter the following data. (IMAGE1 in the IMAGE NAME column refers to NAME, IMAGE2 refers to CITY, and so forth.) The letter a in the TYPE field tells FORMGEN to make the NAME field an alphabetic field. The letters uc in the ATTRIBUTES field tells FORMGEN to define the uppercase attribute for the NAME field and to display the contents of the field in uppercase. 2 14 7831 2279 005
FORMGEN Processor Tutorial EXAMPLE 0 NAME: 1 CITY: 2 STATE: 3 EDUCATION: 4 EDUCATION: 4 DPS 2200 FORMGEN PROCESSOR Image/Field Attributes ------------------- STARTING LINE 1 (n,+n,-n) STARTING FIELD 1 (n,+n,-n) IMAGE NAME TYPE ATTRIBUTES ( ^ = alternate select menu) 1 name a uc 2 city X 3 state X 4 education X Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP When you finish entering data, press XMIT. FORMGEN redisplays the Image/Field Attributes menu, with the values you entered now displayed in uppercase. FORMGEN also displays the following message on line 24: *** IMAGE AND FIELD ATTRIBUTES UPDATED *** :AUTO * Step 13 Press F4. FORMGEN displays a form containing information about the Initial Values function. This capability lets you insert an initial value so that this value is provided when your form is first displayed. This makes your form easier to use and saves time. When you finish reading the information screen, press XMIT. FORMGEN displays the Initial Values form. 7831 2279 005 2 15
FORMGEN Processor Tutorial The Initial Values form looks as follows. NAME: CITY: STATE: EDUCATION: EDUCATION: Tab to the STATE field and enter MN. The space between the colon and the start of the field is protected. You cannot enter any data into it. Press XMIT. FORMGEN redisplays the form with MN in the STATE field. The Initial Values form looks as follows. NAME: CITY: STATE: MN EDUCATION: EDUCATION: If the form is okay, press XMIT a second time. If the form is not okay, change it and press XMIT. After transmitting, check the form. If it is okay, press XMIT a second time and go to the next step. FORMGEN displays the following message on line 24: *** FIELD INITIAL VALUES UPDATED *** :AUTO * 2 16 7831 2279 005
FORMGEN Processor Tutorial Step 14 FORMGEN displays the first Form-Level Attributes menu. (This is the same menu displayed in step 2.) This step lets you make changes to the menu. For example, you may want to enter the final cursor field name now if you do not want to accept the default. As before, press XMIT to move between menus. When you are satisfied with the form-level attributes, press F4. FORMGEN displays the main menu. You have completed defining the form and you can now save it in the form library. 2.1.6. Saving the Form Step 15 You must save the form so FORMGEN can assign a form number to it and so that the run-time functions can use the form. Because you entered 0 into the Form number field in step 2, FORMGEN assigns the next form number in sequence. To save the form, enter SAV into the Library command field and press XMIT. FORMGEN saves the form and displays the Main Menu, with the next available form number (for example, 1) in the Form number field and the following message on line 24: *** EXAMPLE/1 SAVED INTO FORM LIBRARY *** Step 16 After saving the form, generate either COBOL, FORTRAN, or C working storage for the application programs. Enter W in the Select function field and press XMIT. FORMGEN displays the Generate W/S menu with the default values shown. On this menu, instruct FORMGEN to create a symbolic element containing a data structure defining a form in the workspace, form library, or omnibus file. This data structure is known as working storage. The working storage for a form is copied or included into a COBOL, FORTRAN, or C application program when it is compiled. The working storage enables a program to access the data entered in a form and also to change the data displayed in a form. You must save working storage in an element. You can specify a file and element name in the Output field. If a file name is not specified, TPF$ is assumed. 7831 2279 005 2 17
FORMGEN Processor Tutorial If an element name is not specified, FORMGEN uses the following default element name: SCREENn/vvvv where n vvvv is the number of the form. is one of the following: COBP, if generating ASCII COBOL or UCS COBOL working storage FTNP, if generating FORTRAN working storage. H, if generating C working storage. For COBOL and FORTRAN, you must call the Procedure Definition Processor (PDP) to process this element after you exit from the FORMGEN processor. EXAMPLE 1 DPS 2200 FORMGEN PROCESSOR Generate W/S Form name EXAMPLE Form number 1 Workspace Y (Y-Yes, N-No) File type F <F> (F-Formlib, O-Omnibus) Form library SCREEN$FILE Omnibus name (qual*file.elt/vs) Language COB <COB> (COB-ASCII COBOL, FOR-FORTRAN, UC-UCS C, UCOB-UCS COBOL) Output type F <F> (F-File, R-Repository) Initial values Y <Y> (N-No, Y-Yes) Generate prefix Y (N-No, Y-Yes) Allow redefine N <N> (N-No, Y-Yes) Storage type D <D> (D-Default, T-Typedef) Output (qual*file.elt/vs) Select function (A,D,E,F,L,M,O,P,R,U,V,W,X): FKEYS: 1=MAIN 2=REFRESH 3=UNDO 4=WALKTHRU 5=EXIT 6=OMIT 7=HELP 2 18 7831 2279 005
FORMGEN Processor Tutorial Step 17 Press XMIT. FORMGEN displays the following message on line 24: *** WORKING-STORAGE IN FILE: TPF$.SCREEN-1/COBP *** where TPF$.SCREEN-1/COBP is the default output file name. Step 18 Press F1. FORMGEN displays the Main Menu. You are now back where you were in step 2. This completes the example and the form you created can be used. The working storage generated for your form is now stored in the file named in step 16. 2.1.7. Deleting Test Forms Step 19 To delete your completed form or any test or trial forms existing in the form library and workspace, perform the following steps (FORMGEN is still displaying the Main Menu). If you want to print a hard copy of your form, see Section 3 before deleting it. Delete your form from the workspace: 1. Enter DEL in the Library command field. 2. Press XMIT. FORMGEN deletes the form and displays the following message on line 24: *** WORKSPACE IS NOW EMPTY *** Erase your form from the form library: 1. Enter ERA in the Library command field. 2. Press XMIT. 3. Enter ERA in the Library command field and press XMIT a second time. FORMGEN erases the form and displays the following message on line 24: *** EXAMPLE/1 ERASED FROM FORM LIBRARY *** Your task of creating, saving, and deleting your form is complete. To exit FORMGEN, press F5. 7831 2279 005 2 19
FORMGEN Processor Tutorial 2 20 7831 2279 005
Section 3 FORMGEN Processor Reference This section describes the FORMGEN processor, an interactive component of the DPS 2200. It contains reference information for the applications programmer. It explains in detail how to call and exit FORMGEN, how to define your user profile, how to print a form, and how to display help forms. It also describes the contents of each field in each menu and what they are used for. 3.1. Calling FORMGEN The DPS 2200 FORMGEN processor enables you to create and change forms to meet the unique requirements at your site. FORMGEN combines the default attributes that satisfy your requirements with the attributes that you change and the data you enter to produce a form. There are several options available on the call statement. Normally, you do not use any of these options when you call FORMGEN because the applicable operating parameters are determined when your site administrator configures the system. Select the S or L option only to override the parameters selected during system configuration. Call the FORMGEN processor with the following statement: @FORMGN,options device-type where options A I Lets you recover a form from the auto-recovery file if you entered the O option in the Select function field or if you pressed function key 6 (F6) the last time you exited FORMGEN. If you entered E in the Select function field or pressed function key 5 (F5) and FORMGEN could not save your form, use this option to attempt to recover it. Auto-recovery overrides this function. Reinitializes FORMGEN. FORMGEN executes the D$GETDEVICE function, which determines the terminal type. This is useful if you entered a terminal type in the processor statement and you want FORMGEN to determine the real terminal type. 7831 2279 005 3 1
FORMGEN Processor Reference T Y Selects data tracing. Selecting this option executes the D$DUMP function and takes a FORMGEN dump after each input or when FORMGEN detects a fatal error on a DPS 2200 function call. Sets the training mode if TIP files are used. If TIP files are used as form libraries, use the training file instead of the production file. Test mode files are displayed for forms stored in training mode. device-type Terminal mnemonic used to specify if the terminal you are using differs from the terminal type defined as the primary terminal type when your system was configured. If you do not specify a device type, FORMGEN determines the type by using the D$GETDEVICE function (see the DPS 2200 Programming Reference Manual) the first time FORMGEN is called during a run. When you specify a device type, you override the D$GETDEVICE function. Table 3 1 lists the available device-type mnemonics. Table 3 1. Device Type Mnemonics Mnemonic Device Type U200, 200, U2 UNISCOPE 200, UTS 400 in UNISCOPE 200 mode (PROTECT switch on) UTS400, U400, U4, 400 UTS20, U20, 20 UTS 20 UTS30, U30, 30 UTS 30 UTS40, U40, 40 UTS 40 UTS60, U60, 60 UTS 60 DS40, D40, D4 SVT1120, SVT1121, SVT1126 STEP20 UTS 400 in native mode Dataspeed Unisys Video Terminals 1120, 1121, 1126 STEP60 Unisys PC with STEP 60 IBM3270, I3270, 3270 LT300 Unisys LAN terminal 300 Unisys PC with Synchronous Terminal Emulation Package (STEP 20) IBM 3270 series (IBM 3270, IBM 3276, IBM 3277, IBM 3178/3278) with 24x80 form 3 2 7831 2279 005