HP OpenVMS Systems Documentation

When you install the Request Interface, the installation procedure creates the system logical ACMS$RI_EXAMPLES, which is a subdirectory of the ACMS$EXAMPLES directory. It also creates a new CDD dictionary,
ACMS$RI_CDD, under the ACMS$DIR dictionary.

This appendix lists the files included with the Request Interface software. Table E-1 gives the name and location of the components that are on the kit.

For more information on these components, continue on to the next sections of this appendix.

E.1 Application Independent Modules

• ACMS$RI_AGENT.B32
  The ACMS$RI_AGENT is an example of how an agent program can be developed to utilize the RI interface. The ACMS$RI_AGENT uses the Systems Interface (SI) to sign users in to ACMS and call tasks in an ACMS application, just like any other ACMS agent.
  The ACMS$RI_AGENT allows a choice of two different user interfaces to enter the task and application selections. The first interface is a user-written menu interface. This type of interface requires that a programmer write two special purpose procedures: an initialization procedure names ACMS$RI_MENU_INIT, and a menu interface procedure names ACMS$RI_MENU_ROUTINE. These two menu routines can be included into the ACMS$RI_AGENT code in one of two ways:
  • The ACMS$RI_MENU_INIT procedure and the ACMS$RI_MENU_ROUTINE procedure can be linked into a shared image and then, at run time, dynamically activated. The shareable image is activated into the RI agent process, using the LIB$FIND_IMAGE_SYMBOL RTL routine. In order to activate these routines in the ACMS$RI_AGENT, the user must define the logical ACMS$RI_MENU that points to the shared image file that contains the two procedures.
  • The ACMS$RI_MENU_INIT procedure and the ACMS$RI_MENU_ROUTINE procedure can be linked directly into the RI agent code and called as required.
  
  The second interface is the default interface. If the user chooses not to write a menu interface, ACMS$RI_AGENT prompts the user for the task and application desired.
  With either interface, the ACMS$RI_AGENT signs the user in to the ACMS system. The agent then calls the ACMS$INIT_EXCHANGE_IO service and specifies the ACMS$M_IO_ENABLE_SYNC_RI flag. This flag indicates to the ACMS system, EXC specifically, that all task I/O will be executed in the agent process synchronously.
• ACMS$RI_DEBUG.B32
  This is the source code for the Request Interface (RI) supplied debugger module. The debugger module signals with an SS$_DEBUG status, which acts like pressing [Ctrl/Y] and then typing DEBUG at the DCL prompt. If you include this module in the Request Interface request library shared image file, the first time this library file is accessed the OpenVMS debugger prompt (DBG>) appears. This allows you to set breakpoints at User Request Procedures (URPs) so you can debug the request procedure code.
• ACMS Request Interface AGENT and DEBUG object module library, ACMS$RI.OLB
  This is the object library that contains the RI agent object and the RI debugger module object. It contains the following modules:
  • ACMS$RI_AGENT
    RI agent object module is provided so you are not required to write an agent to make use of RI facility. In addition, users may want to code their own menu interfaces and link them directly into the RI agent code.
  • ACMS$RI_DEBUG
    Debug object module which, if included in the RI request library shared image file, allows users to test and debug their user request procedures (URPs) using the OpenVMS debugger. This must be linked into the shared image file.
• ACMS Request Interface Agent executable image(s), ACMS$RI_AGENT.EXE
  This is the supplied RI agent executable image, which can be used to activate the menu interface shared image or to debug URPs. By default, this agent prompts you for task name and application name. In addition, if the default prompt mode is selected, it displays the error (or success) message of a selected task.
• ACMS Request Interface MENU (FMS menu) source modules, ACMS$RI_FMS_MENU.BAS
  This is the source code for the supplied FMS menu interface. It contains the two special-purpose procedures, an initialization procedure called ACMS$RI_MENU_INIT and a user interface (menu) procedure named ACMS$RI_MENU_ROUTINE.
  • ACMS$RI_MENU_INIT
    This module is BASIC FUNCTION source code for the initialization procedure for the FMS Menu interface. This procedure creates the FMS workspaces, attaches the terminal, and opens the FMS Menu form library pointed to by the logical ACMS$RI_FMS_MENU_LIB.
  • ACMS$RI_MENU_ROUTINE
    This module is BASIC FUNCTION source code for the FMS menu interface. This procedure displays a menu and prompts the user for a selection. The FMS menu interface duplicates some of the ACMS menu functionality (*, -, $EXIT, $HELP, keyword, number). This procedure uses the named data functionality of FMS. To adapt this FMS interface to your specific requirements, you need to change only the supplied FMS forms; you do not need to change the FMS interface procedures.
• ACMS Request Interface MENU object module library, ACMS$RI_FMS_MENU.OLB
  This is the Request Interface FMS menu interface object module library. It contains the ACMS$RI_MENU_INIT and the ACMS$RI_MENU_ROUTINE object modules. With it, you can link the FMS menu interface directly into the RI agent code.
• ACMS Request Interface 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, task or menu indicator (T or M) and some 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. 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 that explains what functionality is available under the FMS menu interface such as *, -, $EXIT, number, keyword, and so on. Include this form in all FMS menu interface form libraries.
• ACMS Request Interface FMS menu form library, FMS_MENU_LIBRARY.FLB
  This is the FMS form library that contains the MENU_MAIN_FORM and the MENU_HELP_FORM. The name of the form library is not important since the FMS menu interface uses a logical (ACMS$RI_FMS_MENU_LIB) to point to the proper FMS form library.

This section describes the components of the ACMS Request Interface SMG and QIO sample application source modules. In general, the RI sample application uses SMG and QIO user request procedures (URPs) to do terminal I/O. There are two task group definitions: one uses .RLB request libraries, and the other uses an EXE shareable image file in the REQUEST LIBRARY IS clause. All these components are located in the ACMS$RI_EXAMPLES directory.

E.2.1 RI Sample Application Source Modules

This section lists the sample applicaton source modules for the RI sample application.

• RI_EMPLOYEE_RECORD.CDO record definition
  This is the CDD record definition for the ACMS Request Interface (RI) SMG and QIO sample application. The record contains three fields: the EMPLOYEE ID NUMBER, EMPLOYEE FIRST NAME, and EMPLOYEE LAST NAME.
• RI_APPL_FORMS.BAK --- CDD backup of FMS form definitions
  This is the CDD backup of the FMS forms used in the SMG and QIO sample application. It contains the following forms:
  • RI_ADD_FORM
    TDMS form used in the add request that is used in the add task example.
  • RI_INQ_FORM
    TDMS form used in the inquire request that is used in the inquiry task.
  • RI_INQ_DISP_FORM
    TDMS form used in the inquire display request that is used in the inquiry task.
• FMS request definitions
  • RI_ADD_REQUEST.RDF
    This is the TDMS request definition used in the RI_ADD_TASK task in the SMG and QIO sample application. It prompts the user to enter employee ID, employee first name, and employee last name.

  • RI_INQ_REQUEST.RDF
    This is the TDMS request definition used in the RI_INQ_TASK task in the SMG and QIO sample application. It prompts the user to enter employee ID.
  • RI_INQ_DISP_REQUEST.RDF
    This is the TDMS request definition used in the RI_INQ_TASK task in the SMG and QIO sample application. It displays the employee ID, employee first name, and employee last name.
• TDMS request library definition (includes BUILD command),
  RI_REQUEST_LIBRARY.LDF
  This is the request library definition for the two TDMS request libraries. It also includes the BUILD command to build the request libraries
  RI_REQUEST_LIBRARY1.RLB and RI_REQUEST_LIBRARY2.RLB.
• Task definitions
  • RI_ADD_TASK.TDF
    This is the ACMS Task Definition for the add task in the sample application. The task has one exchange step and one processing step. The exchange step prompts the user to enter employee ID, employee first name, and employee last name and then the processing step writes the data out to an RMS datafile using employee ID as the key. The task contains no control action or program request keys.
  • RI_INQ_TASK.TDF
    This is the ACMS Task Definition for the inquire task in the 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 no control action or program request keys.
• Task group definition (includes BUILD command)
  • RI_LOGICAL_GROUP.GDF
    This is the ACMS task group definition for the RI SMG and QIO 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)). If you build the ACMS application using this task group definition, you must define a logical name (ACMS$RI_LIB_libraryname) to use the SMG or QIO user request procedures for this group. By default, the sample SMG/QIO application was built using the logical name task group definition. In order to make use of the SMG or QIO procedures, you must define the ACMS$RI_LIB_libraryname logical. The definition also includes the BUILD command to build the task group (.TDB).
  • RI_PASSED_GROUP.GDF
    This is the ACMS task group definition for the RI SMG and QIO sample application. This task group defines a request library shared image (.EXE) file in the REQUEST LIBRARY IS clause. If you build the ACMS application using this task group definition, you do not need a logical to use the SMG or QIO user request procedures for this group. This definition also includes the BUILD command to build the task group (.TDB).
• Procedure server source modules
  • RI_INIT_PROCEDURE.COB
    This is the COBOL source code for the initialization routine for the SMG/QIO sample application server procedure. The routine opens an RMS datafile called RI_SIMPLE_APPL.DAT.
  • RI_ADD_PROCEDURE.COB
    This is the COBOL source code for the add routine for the SMG/QIO sample application server procedure. This procedure is used in the
    RI_ADD_TASK to store a record containing employee ID, employee first name, and employee last name.
  • RI_GET_PROCEDURE.COB
    This is the COBOL source code for the get routine for the SMG/QIO sample application server procedure. This procedure is used in the
    RI_INQ_TASK to retrieve a record containing employee ID, employee first name, and employee last name.
  • RI_TERM_PROCEDURE.COB
    This is the COBOL source code for the termination routine for the SMG/QIO sample application server procedure. The routine closes the RMS datafile called RI_SIMPLE_APPL.DAT.
• Command procedures to COMPILE and LINK the procedure server
  • RI_SERVER_COMPILE.COM
    This is a command procedure to recompile all the procedure server modules. It also creates a new object library
    (RI_SERVER.OLB) and inserts all the server modules.
  • RI_SERVER_LINK.COM
    This is a command procedure to relink the procedure server modules into SMG/QIO sample application server image. It uses the server object library created in the recompile command procedure.
• Application definition (includes BUILD command), RI_SAMPLE_APPL.ADF
  This is the ACMS application definition for the RI SMG and QIO sample application. It uses the RI_LOGICAL_GROUP.TDB task group. The definition includes the BUILD command to build the application database (.ADB).
• Menu definition (includes BUILD command), RI_APPL_MENU.MDB
  This is the ACMS menu definition for the RI SMG and QIO sample application. It includes the BUILD command to build the menu database (.MDB).
• Request Interface user request procedure (URP) source modules
  • RI_FORTRAN_QIO.FOR
    This is the FORTRAN source code for the RI request library file that contains all the user request procedures (URPs) for the RI QIO sample application. The URPs use the OpenVMS QIO system service to read and write to the terminal. This file contains the following URP source modules:
    • ACMS$RI_LIB_INIT
      This is the FORTRAN FUNCTION source code for the initialization procedure for the RI request library shared image file. This assigns a channel to the current terminal using the OpenVMS SYS$ASSIGN system service.
    • ACMS$RI_LIB_CANCEL
      This is the FORTRAN FUNCTION source code for the cancellation procedure for the RI request library shared image file. This cancels all outstanding terminal I/O, using the OpenVMS SYS$CANCEL system service, and signals an ACMS cancel error.
    • RI_ADD_REQUEST
      This is the FORTRAN FUNCTION source code to duplicate the TDMS add request by using the OpenVMS SYS$QIOW system service to prompt the user for employee ID, employee first name, and employee last name. The employee record workspace (RI_EMPLOYEE_RECORD) is passed to it as a parameter.
    • RI_INQ_REQUEST
      This is the FORTRAN FUNCTION source code to duplicate the TDMS inquire request by using the OpenVMS SYS$QIOW system service to prompt the user for employee ID number. The employee record (RI_EMPLOYEE_RECORD) workspace is passed to it as a parameter.
    • RI_INQ_DISP_REQUEST
      This is the FORTRAN FUNCTION source code to duplicate the TDMS inquire display request by using the OpenVMS SYS$QIOW system service to display the employee first name and the employee last name. The employee record workspace (RI_EMPLOYEE_RECORD) is passed to it as a parameter.
  • RI_BASIC_SMG.BAS
    This is the BASIC source code for RI request library file that contains all the user request procedures (URPs) for the RI SMG sample application. The URPs use the OpenVMS SMG Run-Time Library (RTL) service to read and write to the terminal. This file contains the following URP source modules (note that this file does not contain an optional cancel URP):
    • ACMS$RI_LIB_INIT
      This is the BASIC FUNCTION source code for the initialization procedure for the RI request library shared image file. This creates a pasteboard and a keyboard for the terminal using the OpenVMS SMG RTL services.
    • RI_ADD_REQUEST
      This is the BASIC FUNCTION source code to duplicate the TDMS add request by using the OpenVMS SMG RTL services to prompt the user for employee ID, employee first name, and employee last name. The employee record workspace (RI_EMPLOYEE_RECORD) is passed to it as a parameter.
    • RI_INQ_REQUEST
      This is the BASIC FUNCTION source code to duplicate the TDMS inquire request by using the OpenVMS SMG RTL services to prompt the user for employee ID number. The employee record workspace (RI_EMPLOYEE_RECORD) is passed to it as a parameter.
    • RI_INQ_DISP_REQUEST
      This is the BASIC FUNCTION source code to duplicate the TDMS inquire display request by using the OpenVMS SMG RTL services to display the employee first name and the employee last name. The employee record workspace (RI_EMPLOYEE_RECORD) is passed to it as a parameter.
• Command procedures to COMPILE and LINK the request library shared image file:
  • RI_REQ_LIB_COMPILE.COM
    This is a command procedure to recompile both the user request procedure modules for the SMG and the QIO request library shared image file. It also creates two new object libraries (RI_FORTRAN_QIO.OLB and RI_BASIC_SMG.OLB) and inserts all URP modules in the appropriate object library.
  • RI_REQ_LIB_LINK.COM
    This is a command procedure to relink the user request procedure modules into the request library shared image file used in the RI_SAMPLE_APPLICATION. It uses the object library created in the recompile command procedure.

This section lists the run-time files for the RI sample application.

• TDMS request library file (RLB)
  • RI_REQUEST_LIBRARY1.RLB
    This is the TDMS request library for the RI SMG/QIO sample application. It contains the RI_ADD_REQUEST request and the RI_INQ_REQUEST request. The reason for splitting the TDMS request between two TDMS request libraries is to demonstrate the use of a URP and a TDMS request in a single task (RI_INQ_TASK).
  • RI_REQUEST_LIBRARY2.RLB
    This is the TDMS request library for the RI SMG/QIO sample application. It contains the RI_INQ_DISP_REQUEST request.
• Task group database (TDB)
  • RI_LOGICAL_GROUP.TDB
    This is the ACMS task group database for the RI SMG and QIO 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)). If you build the ACMS application using this task group database, you must define a logical name (ACMS$RI_LIB_libraryname) to use the SMG or QIO user request procedures for this group. By default, the sample SMG/QIO application was built using the logical name task group database. To make use of the SMG or QIO procedures, you must define the ACMS$RI_LIB_libraryname logical.
  • RI_PASSED_GROUP.TDB
    This is the ACMS task group database for the RI SMG and QIO sample application. This task group defines a request library shared image (.EXE) file in the REQUEST LIBRARY IS clause. If you build the ACMS application using this task group database, no logical is needed to use the SMG or QIO user request procedures for this group.
• RI_SERVER.OLB---Procedure server object module library
  This is the object library containing the four object modules that make up the RI server used in the SMG/QIO sample application. It includes the following four modules:
  • RI_INIT_PROCEDURE---Object module for the initialization procedure
  • RI_TERM_PROCEDURE---Object module for the termination procedure
  • RI_ADD_PROCEDURE ---Object module for the add record procedure
  • RI_GET_PROCEDURE ---Object module for the get record procedure
• RI_SERVER.EXE---Procedure Server image file
  This is the procedure server image for the RI SMG/QIO sample application.
• RI_SAMPLE_APPL.ADB---Application Database (ADB)
  This is the ACMS application database for the RI sample application. It uses the RI_LOGICAL_GROUP.TDB task group.
• RI_APPL_MENU.MDB---Menu Database (MDB)
  This is the ACMS menu database for the RI sample application.
• Request Interface User Request Procedure object module library
  • RI_BASIC_SMG.OLB
    This is the object library that contains the object modules for the SMG URPs contained in the RI request library shared image file. It contains the following object modules:
    • ACMS$RI_LIB_INIT
      This is the object module for the RI request library shared image file initialization user request procedure.
    • RI_ADD_REQUEST
      This is the object module for the RI request library shared image file add request user request procedure.
    • RI_INQ_REQUEST
      This is the object module for the RI request library shared image file inquiry request user request procedure.
    • RI_INQ_DISP_REQUEST
      This is the object module for the RI request library shared image file inquiry display user request procedure.

  • RI_FORTRAN_QIO.OLB
    This is the object library which contains the object modules for the QIO URPs contained in the RI request library shared image file. It contains the following object modules:
    • ACMS$RI_LIB_INIT
      This is the object module for the RI request library shared image file initialization user request procedure.
    • ACMS$RI_LIB_CANCEL
      This is the object module for the RI request library shared image file cancellation user request procedure.
    • RI_ADD_REQUEST
      This is the object module for the RI request library shared image file add request user request procedure.
    • RI_INQ_REQUEST
      This is the object module for the RI request library shared image file inquiry request user request procedure.
    • RI_INQ_DISP_REQUEST
      This is the object module for the RI request library shared image file inquiry display user request procedure.
• Request Interface request library shared image file
  • RI_BASIC_SMG.EXE
    This is the SMG RI request library shared image file that includes all SMG URP modules.
  • RI_FORTRAN_QIO.EXE
    This is the QIO RI request library shared image file that includes all QIO URP modules.