HP OpenVMS Systems Documentation
Content starts here

Compaq ACMS for OpenVMS
Writing Applications
Previous Contents Index

E.3 FMS Sample Application

This section describes the components of the FMS sample application. In general, the FMS sample application uses FMS user request procedures written in FORTRAN to replace the TDMS requests included in the request libraries that are defined in the task group definition. This requires the use of the ACMS$RI_LIB_libraryname logical. All the components listed are in the ACMS$RI_EXAMPLES directory.

E.3.1 FMS Sample Application Source Modules

This section lists the source modules for the FMS sample application.

  • Record definitions
    • FMS_EMPLOYEE_RECORD.DDL
      This is the CDD record definition for the ACMS Request Interface (RI) FMS sample application. The record contains employee information.
    • FMS_WORKSPACE_RECORD.CDO
      This is the CDD record definition for the ACMS RI FMS sample application. The record contains two fields: the program request key field and the error status field.
    • FMS_SCROLL_RECORD.CDO
      This is the CDD record definition for the ACMS RI FMS sample application. The record contains scroll area information.
    • FMS_SALARY_RECORD.CDO
      This is the CDD record definition for the ACMS RI FMS sample application. The record contains the salary range information used by the FMS user action routines to demonstrate cross-field validation.
  • FMS_FORM.BAK---CDD backup of TDMS form definitions
    This is the CDD backup of the TDMS forms used in the FMS sample application. It contains the following forms:
    • FMS_ADD_FORM
      TDMS form used in the add request that is used in the add task example.
    • FMS_INQ_FORM
      TDMS form used in the inquiry request and the inquiry display request that is used in the inquiry task.
    • FMS_UPD_FORM
      TDMS form used in the inquiry update request and the display/modify request that is used in the update task.
    • FMS_SCROLL_FORM
      TDMS form used in the inquiry scroll request that is used in the scroll task.
    • FMS_SCROLL_DISP_FORM
      TDMS form used in the display scroll request that is used in the scroll task.
  • TDMS request definitions
    • FMS_ADD_REQUEST.RDF
      This is the TDMS request definition used in the FMS_ADD_TASK task in the FMS_SAMPLE application. It prompts the user to enter all employee information.
    • FMS_INQ_REQUEST.RDF
      This is the TDMS request definition used in the FMS_INQ_TASK task in the FMS_SAMPLE application. It prompts the user to enter the employee badge number.
    • FMS_INQ_DISP_REQUEST.RDF
      This is the TDMS request definition used in the FMS_INQ_TASK task in the FMS_SAMPLE application. It displays employee information that was requested in the inquire request.
    • FMS_UPD_REQUEST.RDF
      This is the TDMS request definition used in the FMS_UPD_TASK task in the FMS_SAMPLE application. It prompts the user to enter the employee badge number. This is the same as the FMS_INQ_REQUEST.
    • FMS_UPD_DISP_REQUEST.RDF
      This is the TDMS request definition used in the FMS_UPD_TASK task in the FMS_SAMPLE application. It displays the employee information requested in the update request; it then allows users to modify the employee information.
    • FMS_SCROLL_REQUEST.RDF
      This is the TDMS request definition used in the FMS_SCROLL_TASK task in the FMS_SAMPLE application. It prompts the user to enter an employee last name.
    • FMS_SCROLL_DISP_REQUEST.RDF
      This is the TDMS request definition used in the FMS_SCROLL_TASK task in the FMS_SAMPLE application. It displays employee last name, employee first name, and employee badge number for all employees with the specified last name from the FMS_SCROLL_REQUEST.
  • TDMS request library definition (includes BUILD command),
    FMS_REQUEST_LIBRARY.LDF
    This is the request library definition for the TDMS request libraries. This also includes the BUILD command to build the request library FMS_REQUEST_LIBRARY.RLB.
  • Task definitions
    • FMS_ADD_TASK.TDF
      This is the ACMS task definition for the add task in the FMS_SAMPLE application. The task has one exchange step and one processing step. The exchange step prompts the user to enter the employee information, and then the processing step writes the data out to an RMS datafile using employee ID as the key. The task contains control action for duplicate records and a program request key for [PF1/E].
    • FMS_INQ_TASK.TDF
      This is the ACMS task definition for the inquire task in the FMS_SAMPLE application. The task has two exchange steps and one processing step. The first exchange step prompts the user to enter employee ID. The processing step retrieves the employee information from an RMS datafile using employee ID as the key; then the second exchange step displays the employee information retrieved from the previous processing step. The task contains control action for record not found and a program request key for [PF1/E].
    • FMS_UPD_TASK.TDF
      This is the ACMS Task Definition for the update task in the FMS_SAMPLE application. The task has two exchange steps and two processing step. The first exchange step prompts the user to enter employee ID. The processing step retrieves the employee information from an RMS data file using employee ID as the key. The second exchange step displays the employee information retrieved from the previous processing step and lets user modify the employee data. Then the second processing step rewrites the data record to the file. The task contains control action for record not found and a program request key for [PF1/E].
    • FMS_SCROLL_TASK.TDF
      This is the ACMS task definition for the scroll task in the FMS_SAMPLE application. The task has two exchange steps and one processing steps. The first exchange step prompts the user to enter the last name. The processing step retrieves employee information on all employees with that last name from an RMS datafile, using employee last name as the key. Then the second exchange step displays the employee information retrieved from the previous processing step in a scroll region. The task contains control action for record not found and a program request key for [PF1/E].
  • Task group definition (includes BUILD command), FMS_GROUP.GDF
    This is the ACMS task group definition for the RI FMS sample application. This group does not define a shared image (.EXE) file in the REQUEST LIBRARY IS clause. You must define a logical name to use the RI for this group. This also includes the BUILD command to build the task group database FMS_GROUP.TDB.
  • Procedure server source modules
    • FMS_INIT_PROCEDURE.COB
      This is the COBOL source code for the initialization routine for the FMS sample application server procedure. The routine opens an RMS datafile called FMS_APPL.DAT.
    • FMS_ADD_PROCEDURE.COB
      This is the COBOL source code for the add routine for the FMS sample application server procedure. This procedure is used in the FMS_ADD_TASK to store a record containing the employee information.
    • FMS_GET_PROCEDURE.COB
      This is the COBOL source code for the get routine for the FMS sample application server procedure. This procedure is used in the FMS_INQ_TASK and FMS_UPD_TASK to retrieve a record containing all employee information using the EMPLOYEE_ID as the key.
    • FMS_UPDATE_PROCEDURE.COB
      This is the COBOL source code for the update routine for the FMS sample application server procedure. This procedure is used in the FMS_UPD_TASK to rewrite the record after the user modifies it.
    • FMS_SCROLL_PROCEDURE.COB
      This is the COBOL source code for the get scroll data routine for the FMS sample application server procedure. This procedure is used in the FMS_SCROLL_TASK to retrieve employee information for all employees with a specified last name.
    • FMS_TERM_PROCEDURE.COB
      This is the COBOL source code for the termination routine for the FMS sample application server procedure. The routine closes the RMS datafile called FMS_APPL.DAT.
  • Message source file, FMS_MESSAGES.MSG
    This is the message file source that contains the error messages for the FMS sample application. These messages are displayed using the ACMS GET MESSAGE clause.
  • Command Procedure to build message file, FMS_MESSAGES.COM
    This is a command file to build the FMS messages file.
  • Command Procedures to COMPILE and LINK the procedure server
    • FMS_SERVER_COMPILE.COM
      This is a command procedure to recompile all the procedure server modules. It also creates a new object library (FMS_SERVER.OLB) and inserts all server modules.
    • FMS_SERVER_LINK.COM
      This is a command procedure to relink the procedure server modules into FMS sample application server image. It uses the server object library created in the recompile command procedure.
  • Application Definition (includes BUILD command), FMS_APPLICATION.ADF
    This is the ACMS application definition for the RI FMS sample application. It uses the FMS_GROUP.TDB task group and includes the BUILD command to build the application database (.ADB).
  • Menu Definition (includes BUILD command), FMS_APPLICATION_MENU.MDB
    This is the ACMS menu definition for the RI FMS sample application. It includes the BUILD command to build the menu database (.MDB).
  • FMS form definitions
    • FMS_ADD_FORM.FRM
      This is the FMS form used in the add request URP that the add task example uses.
    • FMS_INQ_FORM.FRM
      This is the FMS form used in the inquiry request URP that is used in the inquiry task.
    • FMS_DISP_FORM.FRM
      This is the FMS form used in the inquiry display request URP that is used in the inquiry task.
    • FMS_DEP_FORM.FRM
      This is the FMS form used in the inquiry display request URP and the update display request URP that is used in the inquiry task/update task.
    • FMS_UPD_FORM.FRM
      This is the FMS form used in the update inquiry request URP that is used in the update task.
    • FMS_SCROLL_FORM.FRM
      This is the FMS form used in the inquiry scroll request that is used in the scroll task.
    • FMS_SCROLL_DISP_FORM.FRM
      This is the FMS form used in the display scroll request that is used in the scroll task.
    • FMS_HELP_FORM.FRM
      This is the FMS form used as a help form to the FMS_ADD_FORM.FRM.
  • Command Procedure to build the FMS form library, FMS_BUILD_FORM_LIB.COM
    This is a command procedure that builds the FMS form library for the FMS sample application.
  • Request Interface URP source modules
    • FMS_INIT_LIBRARY.COB
      This is COBOL PROCEDURE source code for the initialization procedure for the FMS RI request library. This procedure creates the FMS workspaces, attaches the terminal, and opens the FMS forms library defined by the logical ACMS$RI_FMS_MENU_LIB.
    • FMS_ADD_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS add request by using FMS service calls to prompt the user employee information. The employee record and workspace record are passed to it as parameters.
    • FMS_INQ_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS inquiry request by using the FMS service calls to prompt the user for badge number. The employee record, the ACMS processing status record, and the workspace record are passed to it as parameters.
    • FMS_INQ_DISP_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS inquiry display request by using the FMS service calls to display the employee information. The employee record is passed to it as a parameter.
    • FMS_UPD_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS update request by using the FMS service calls to prompt the user for badge number. The employee record, the ACMS processing status record, and the workspace record are passed to it as parameters.
    • FMS_UPD_DISP_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS inquiry display/modify request by using the FMS service calls to display the employee information and request user updates. The employee record and workspace record are passed to it as parameters.
    • FMS_SCROLL_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS inquiry scroll request by using the FMS service calls to prompt the user for an employee last name. The scroll record, the ACMS processing status record, and the workspace record are passed to it as parameters.
    • FMS_SCROLL_DISP_REQUEST.COB
      This is COBOL PROCEDURE source code to duplicate the TDMS scroll display request by using the FMS service calls to display all employees with the requested last name. The scroll record is passed to it as a parameter.
  • FMS user action routines (UAR) source modules
    • FMS_TITLE_CHECK_UAR.COB
      This is COBOL PROCEDURE source code to execute as a UAR in the FMS add task. It checks the title field entered on the form with a data file named TITLE_SALARY.DAT.
    • FMS_SALARY_CHECK_UAR.COB
      This is COBOL PROCEDURE source code to execute as a UAR in the FMS add task. It checks the salary field entered on the form with a salary range for the entered title field.
  • Command Procedures to COMPILE and LINK Request Library shared image file
    • FMS_REQ_LIB_COMPILE.COM
      This is a command procedure used to recompile the FMS RI request library modules. It also creates a new object library and inserts all the modules.
    • FMS_REQ_LIB_LINK.COM
      This is command procedure used to relink the FMS RI request library shared image. It uses the object library.

E.3.2 FMS Sample Application Run-Time Files

This section contains the run-time files for the FMS sample application.

  • TDMS request library file (RLB), FMS_REQUEST_LIBRARY.RLB
    This is the TDMS request library for the RI FMS sample application. It contains all the TDMS requests for the FMS sample application.
  • Task group database (TDB), FMS_GROUP.TDB
    This is the ACMS task group database for the RI FMS sample application. This group does not define a request library shared image (.EXE) file in the REQUEST LIBRARY IS clause (only TDMS request library files (RLB)). Because the FMS sample application is built using this task group database, you must define a logical name (ACMS$RI_LIB_libraryname) to use the FMS user request procedures for this group.
  • Procedure server object module library, FMS_SERVER.OLB
    This is the object library containing the six object modules that make up the ACMS server used in the FMS sample application. It includes the following modules:
    • FMS_INIT_PROCEDURE
      Object module for the initialization procedure
    • FMS_TERM_PROCEDURE
      Object module for the termination procedure
    • FMS_ADD_PROCEDURE
      Object module for the add record procedure
    • FMS_GET_PROCEDURE
      Object module for the get record procedure
    • FMS_UPDATE_PROCEDURE
      Object module for the update record procedure
    • FMS_SCROLL_PROCEDURE
      Object module for the get scroll data procedure
  • Procedure server image file, FMS_SERVER.EXE
    This is the procedure server image for the RI FMS sample application.
  • Application database (ADB), FMS_APPLICATION.ADB
    This is the ACMS application database for the RI FMS sample application. It uses the FMS_GROUP.TDB task group.
  • Menu database (MDB), FMS_APPLICATION_MENU.MDB
    This is the ACMS menu database for the RI FMS sample application.
  • Application message file, FMS_MESSAGES.EXE
    This is the message file that contains the error messages for the FMS sample application. These messages are displayed using the ACMS GET MESSAGE clause.
  • Request Interface FMS form library, FMS_FORM_LIBRARY.FLB
    This is the FMS form library that contains all the FMS forms used in the FMS sample application.
  • Request Interface request library shared image file, FMS_REQUEST_LIBRARY.EXE
    This is the FMS RI request library shared image file that includes all FMS URP modules.
  • Request Interface URP object module library, FMS_REQ_LIB.OLB
    This is the object library that contains the object modules for the FMS RI request library shared image file.
    • ACMSRI$INIT_LIBRARY
      Object module for the FMS RI request library initialization procedure
    • FMS_ADD_REQUEST
      Object module for the FMS RI request library add request procedure
    • FMS_INQ_REQUEST
      Object module for the FMS RI request library inquiry request procedure
    • FMS_INQ_DISP_REQUEST
      Object module for the FMS RI request library inquiry display request procedure
    • FMS_UPD_REQUEST
      Object module for the FMS RI request library inquiry update request procedure
    • FMS_UPD_DISP_REQUEST
      Object module for the FMS RI request library update display/modify request procedure
    • FMS_SCROLL_REQUEST
      Object module for the FMS RI request library inquiry scroll request procedure
    • FMS_SCROLL_DISP_REQUEST
      Object module for the FMS RI request library display scroll request procedure
    • FMS_TITLE_CHECK_UAR
      Object module for the FMS UAR
    • FMS_SALARY_CHECK_UAR
      Object module for the FMS UAR
  • FMS User Action Routine RMS data file, TITLE_SALARY.DAT
    This is the data file that contains title and salary range information. This matches the FMS_HELP_FORM information.

Appendix F
Modifying the FMS Menu Interface

ACMS software includes an FMS-based menu interface to use with the ACMS-supplied RI agent, ACMS$RI_AGENT. The sample FMS form library for the menu interface is in the ACMS$RI_EXAMPLES directory.

This appendix describes how to modify this menu interface to suit the needs of a particular application. To incorporate the modified menu interface into the ACMS$RI_AGENT, see Chapter 14.

There are two FMS menu form definitions:

  • MENU_MAIN_FORM.FRM
    This is the FMS form used as the top-level (main) menu form. It is similar to the layout of the ACMS default menu format, which includes a number, a keyword, a task or menu indicator (T or M), and descriptive text. At the bottom of the menu is the SELECTION: prompt.
    The menu layout is static text in the FMS form. The only field on the menu form is the selection field. The numbers and keywords are used as named-data indexes and named-data keywords. To change the form for a specific application, modify the static text on the main menu and change the named-data field information. The default main menu is set up for the FMS sample application.
  • MENU_HELP_FORM.FRM
    This is the FMS form used when the user types $HELP or presses [PF2] twice at the SELECTION: prompt. It displays a form explaining the functionality available under the FMS menu interface, such as *, -, $EXIT, number, keyword, and so on. Include this form in all FMS menu interface form libraries.

To modify the supplied FMS menu form, MENU_MAIN_FORM.FRM:

  1. Make a copy of the form. Do not modify the original copy of MENU_MAIN_FORM.FRM; you must modify a copy of the form. The form MENU_MAIN_FORM must stay the same because the menu interface routine uses that name. For example: 


    $ COPY MENU_MAIN_FORM.FRM newmenu.frm
  2. Edit the form to make the necessary changes. 


    $ FMS/EDIT newmenu.frm

    FMS responds by clearing the screen and displaying the Form Editor Menu, shown in Figure F-1. You use this menu to select an action to perform. Type the name of the phase you wish to enter.

    Figure F-1 Form Editor Menu


    First change the layout of the form. To enter the layout phase, type LAYOUT and press [Return].
    The layout of the ACMS-supplied menu form is similar to the ACMS menu format. The FMS menu form contains a menu header, a selection list, a prompt line, and a message line. The menu header is the name of the menu. The selection list shows the tasks you can run and the menus available.
    • The first column in the list is the number of the entry on the menu.
    • The second column is a keyword for the item.
    • The third column is a label identifying the item as a task (T) or a menu (M).
    • The fourth column is text describing the item.
    • The prompt line includes both the SELECTION: prompt and blank spaces after the prompt.

    Type the number or keyword for the task or menu in the blank space after the prompt. Press [Return] after making your selection.
    The FMS menu form contains only one field, the selection field. The remaining data on the screen is background text. In the layout phase, you can change, delete, or add any background text that is needed for a given application; the selection field name and size, however, must remain the same.
    The selection list is also used by the menu interface routines. The FMS menu interface routine uses the selection list numbers as indexes or the selection list keywords as keywords for FMS-named data calls to retrieve the task and application names.
  3. After modifying the FMS menu form layout, change the Named Data Area of the form. Named Data provides a convenient way for the FMS menu routine to store program parameters with the form instead of coding them into the menu routines. Use Named Data to add additional menu forms and change the existing menu form without changing the menu interface routine.
    Named Data is data that is associated with a form but does not appear on the operator's screen. Named Data exists in the FMS workspace with the form. Define the Named Data to the menu form during the data phase. Enter the data phase by typing PHASE at the form editor menu.
    The data can be any string up to 80 characters and is referenced by either name or index. The FMS menu routine subdivides the 80-character data area into ACMS task name and application name. The task name must be first; the application name follows, with at least one space in between them.
    Table F-1 shows how to define the named data associated with a form.

    Table F-1 Defining the Named Data Associated with the Form
    Index Name Data Area
    Task Name/Application
    1 ADD FMS_ADD_TASK / FMS_APPLICATION
    2 DISPLAY FMS_INQ_TASK / FMS_APPLICATION


    The FMS menu interface routine uses the Named Data area to determine the ACMS task name and the ACMS application name by providing the user with two ways to select a task or menu: by number or by keyword. The user can type either the number from the menu (that is used as a index into the Named Data area) or the keyword from the menu (that is used as a keyword into the Named Data area). You can use the short form of a keyword. Use enough letters to make the selection unique.
    The select list numbers and keywords must exactly match the indexes and names in the Named Data area of the menu form. If a user enters a selection that is not contained in the Named Data area, an error message is displayed indicating that it was an invalid selection and to enter another one.
    In addition, the FMS menu interface routines define three keywords that implement some of the ACMS menu functionality. The interface routines keywords must be placed in the task-name field of the Named Data area. The keywords are as follows:
    • MENU
      If the menu interface routine finds the keyword MENU in the task-name field, FMS assumes that the application-name field contains the name of another menu form in the same FMS menu form library. This keyword enables you to develop menu trees.
      The FMS menu interface routine provides two special characters for moving through the menu tree. This is similar to the ACMS menu facility. The special characters are the asterisk (*) for moving up to the main level menu and the hyphen (-) for moving up to the previous level. The FMS menu interface supports five levels of menus.
    • $EXIT
      If the menu interface routine finds the keyword $EXIT in the task-name field, it exits from the RI agent code.
    • $HELP
      If the menu interface routine finds the keyword $HELP in the task-name field, it displays the help form (MENU_HELP_FORM) that is provided in the ACMS$RI_EXAMPLES directory. The help form simply describes the user's options at the selection prompt.
  4. Create a new FMS menu library.
    After modifying the supplied menu form, create a new FMS form library. Use the FMS Form Librarian Utility. Putting forms in form libraries makes the forms available to the Form Driver and the FMS menu interface routine. The create operation makes a new library file and puts one or more binary forms in it, as follows: 


    $ FMS/LIBRARY/CREATE

LIBRARY: newmenulibrary.flb

FORMS:   newmenu.frm,menuhelpform.frm
  5. Link the FMS menu interface routine.
    You can link the FMS menu interface routine directly into the ACMS$RI_AGENT or into a shared image that is activated at run time. See Section 14.5.1 for more information on linking and running the menu interface.

Previous Next Contents Index