All Form Driver routines are called as procedures or as functions. Syntax follows the standard requirements of the language.

The argument passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing arguments:

FMS routines, however, expect arguments to be passed only by reference and by descriptor.

By reference specifies that the storage location of the argument is passed to the routine. FMS expects integers to be passed by reference.

By descriptor specifies that the address of а descriptor data structure is passed to the routine. FMS expects character strings and arrays to be passed by descriptor.

When the call syntax includes optional arguments and you do not wish to specify all of the information, you can use null arguments. Any optional argument can be omitted to simplify your program. In some programming languages, а comma is used as а placeholder for each null argument. In other languages, an address of 0 is assigned to each null argument. Optional arguments to the right of the last required argument can simply be omitted from the call.

Data types that are not recognized by FMS can be used in your application program provided they are not passed to the Form Driver.

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by defining them to be:

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be placed in а common storage area of your program.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. You can utilize your built-in language functions for conversion operations, or you can create your own conversion functions.

You can call any FMS routine as а subprogram or as а function. Syntax follows standard VАХ-11 BASIC requirements.

12235 CALL FDV$WAIT

5070 CALL FDV$GET IDPTIDN$, TERMINAT0RI, '0PTI0N'J

EXTERNAL L0NG FUNCTI0N F0V$GET

RETURN_STATUS = FDV$GET IDPTI0N$, TERMINATDRZ, 'DPTI0N')

The argument passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing arguments:

FMS routines, however, expect arguments to be passed only by reference and by descriptor.

By reference specifies that the storage location of the argument is passed to the routine. FMS expects integers to be passed by reference, which is the BASIC default passing mechanism for integers.

By descriptor specifies that the address of а descriptor data structure is passed to the called routine. FMS expects character strings and arrays to be passed by descriptor, which is the BASIC default passing mechanism for character strings and arrays.

When the call syntax includes optional arguments and you do not wish to specify all of the information, you can use null arguments. Any optional argument can be omitted to simplify your program. А comma functions as а placeholder for each null argument. Optional arguments to the right of the last required argument can simply be omitted from the call. In the following example, the FDV$GETAL call passes only the field terminator value:

14058 CALL FDV$GETAL ( , TERMINATDR%)

BASIC data types that are not recognized by FMS can be used in your BASIC application program provided they are not passed to the Form Driver.

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by defining them to be:

In the Sample Application program, the tca, wksp, and mloc arguments are passed to several Form Driver routines. These arguments are defined as integer array variables. You may alternatively define these variables to be character strings. (The strings can be static or dynamic but must be extended to the proper length.)

The following declarations establish names and storage for the integer array variables WORKSPACE%, CHECKWKSP%, ТСА%, and MENU_FORM%:

130  Dim WORKSPACE% (3)      !General workspace
135  DIM CHECKWKSP% (3)      !Check workspace
140  DIM TCAZ (3)            !Terminal Control Area
145  DIM MENU_FORM% (500)    !Storage for memory-resident form

Note that in BASIC, when an entire array is referenced, the array name must be followed by а set of parentheses () to distinguish the array from а scalar of the same name. Thus, when FDV$ATERM passes the entire array ТСА%, the array name is written as follows:

1040  CALL FDV$ATERM (TCA%) (), 12%, 2%)

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be placed in COMMON. Note that this is not done in the Sample Application program. The sample program's structure protects the workspaces, terminal control areas, and run-time memory-resident form areas implicitly.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, the workspace is allocated and the FDV$AWKSP routine is called. In the DIM statement, 12 bytes (3 longwords) are allocated to workspace. When the FDV$AWKSP routine is called, the first argument (WORKSPACE%) specifies the area of memory to be used for your workspace. The second argument specifies an estimate of the workspace size (2000 bytes) that you will need to display the largest form in your application.

130  DIM WDRKSPACE% (3)              ! General workspace
135  DIM CHECKWKSP% (3)              ! Check workspace

1042 CALL FDV$AWKSP (CHECKWKSP%(), 2000%)
1045 CALL FDV$AWKSP (WORKSPACE%(), 2000%)

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

In the Sample Application, the following steps are taken to get а new account balance after writing а check:

11390  CALL FDM$RET (RI.AMTPAY$.'AMTPAY')
11395  AMTPAY% = OAL(RI.AMTPAY$)
11400  BALANCE% = BALANCE% - AMTPAY%
11405  TOTPAY% = TOTPAY% + AMTPAY%
11410  CALL FDU$PUT (FN.CENTS$ (BALANCE%), 'BALANCE')

15900  DEF FN.CENTS$ (CENTS%)
15950  CENTS$ = FORMAT$ (CENTS%, "######")
15955  FN.CENTS$ = XLATE (CENTS$, STRING$ (32%, 0%), + '0' + &
                 STRING$ (15%, 0%) + '012345S789')
15960  FNEND

In this example, the BASIC VAL function is used to convert the string expression RI.AMTPAY$ to an integer variable АMТРАY%, which is used to hold the data item's value. The integer value of the variable АMТРАY% is subtracted from the integer value BALANCE% to produce а new value for BALANCE%. The value of АMТРАY% is also added to the integer value of the variable ТОТРАY% to produce а new value for ТОТРАY%.

After the data operations have been completed, SAMP.BAS calls the user­created function FN.CENTS$. In that function, the BASIC FORMAT$ function converts а number to а character string with leading blanks. The BASIC XLATE function is then used to replace all blanks with zeros.

The value for the balance is displayed in the right-justified field 'BAL­ ANCE'. The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the character expression are placed to the left of the rightmost digit. If output is longer than the field, FMS truncates on the left. (The Form Driver displays а data length error message (FDV$_DLN) only if you have set FMS Debug mode.)

Note that in this example the output goes to а field with а decimal point field-marker character. In the presence of а decimal point field marker, the Form Driver creates strange-looking output for single-digit data items. The output will be а period followed by а space and then the digit – rather than .01, for example. In the above example, the FORMAT$ and the XLATE functions are used to prevent this kind of unconventional output.

The BASIC built-in function STR$ converts а number to а character string with no leading blanks. Your program can use the STR$ function for data conversion operations if field markers will not create а confusing appearance.

For other conversion options, see the general conversion routines in the VAX-11 Run-Time Library Reference Manual.

The FMS Sample Application program (SAMP.BAS) is part of the FMS distribution kit. When FMS is installed, SAMP.BAS is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, SAMP.BAS shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

$!       SAMPBAS.COM
$!
$!      Compile and link the BASIC version of the FMS V2 Sample Application
$!
$!      The BASIC source files are:      SAMP.BAS
$!
$!      SMP VECTOR.OBJ and SMPMEMRES.OBJ were produced by the FMS commands:
$!
$!        FMS/VECTOR/OUTPUT=SMPVECTOR SAMP.FLB
$!        FMS/MEMORY/OUTPUT=SMPMEMRES SAMP.FLB/FORM=(HELP_KEYS,HELP_MENU)
$!
$ BASIC SAMP
$ LINK  SAMP, FMS$EXAMPLES:SMPVECTOR, FMS$EXAMPLES:SMPMEMRES

You can call any FMS routine as а procedure or as а function. Syntax follows standard VАХ-11 BLISS-32 requirements.

FDV$WAIТ ();

FDV$GET (ОРТION-DSC, TERMINATOR, %ASCID'ОРТION');

STATUS_RETURN=FDV$GET (ОРТION-DSC, TERMINATOR, %ASCID'ОРТION');

The parameter passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing parameters:

FMS routines, however, expect parameters to be passed only by reference and by descriptor.

By reference specifies that the storage location of the parameter is passed to the routine. FMS expects integers to be passed by reference.

By descriptor specifies that the address of а descriptor data structure is passed to the called routine. FMS expects character strings and arrays to be passed by descriptor.

When the call syntax includes optional parameters and you do not wish to specify all of the information, you can use null arguments. Any optional parameter can be omitted to simplify your program. An address of 0 is assigned to each null argument. Optional parameters to the right of the last required parameter can simply be omitted from the call. In the following example, the FDV$GETAL call passes only the field terminator value:

FDV$GETAL (0, TERMINATOR);

BLISS data types that are not recognized by FMS can be used in your BLISS application program provided they are not passed to the Form Driver.

One-dimensional arrays (vectors) are structures that can be used in FMS for the following parameters:

You must provide FMS with storage space for these parameters. You can do that by defining them to be:

In the Sample Application program, the tca, wksp, and mloc parameters are passed to several Form Driver routines. These parameters are defined as integer array descriptors. In the program а distinct macro is constructed for declaring longword integer arrays and their descriptors that are passed by the Form Driver.

The following declarations establish names and storage for the integer array variables WORKSPACE, CHECKWKSP, ТСА, and MENU_FORM. L_ARRAY is а macro in the SAMPBLI.BLI program.

L_ARRAY(
    WORKSPACE,        3,      !General workspace
    CHECKWKSP,        3,      !Check workspace
    ТСА,              3,      !Terminal Control Area
    MENU_FORM,      500,      !Storage for memory-resident forms
    );

You can alternatively define these variables to be character strings. (The strings can be static or dynamic but must be extended to the proper length). Use of character strings rather than longword integer arrays avoids the need to construct а distinct macro for the arrays. Thus, as in the example below, you may wish to declare tca, wksp, and mloc as fixed-length character strings. FIXSTR is а macro in the SAMPBLI.BLI program.

FIXSTR(
    WORKSPACE,    12;
    CHECKWKSP,    12;
    ТСА,          12;
    MENU_FORM,  2000
    );

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be placed in OWN or GLOBAL. Note that this is not done in the Sample Application program. The sample program's structure protects the workspaces, terminal control areas, and run-time memory-resident form areas implicitly.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, workspace is allocated and the FDV$AWKSP routine is called. In the program's declaration section, 12 bytes (3 longwords) are allocated. When FDV$AWKSP is called, the first parameter (WORKSPACE_DSC) specifies the area of memory to be used for your workspace. The second parameter specifies an estimate of the workspace size (2000 bytes) that you will need to display the largest form in your application.

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

You can create your own data conversion functions to help satisfy FMS requirements. The Sample Application has the following data conversion macros:

In the Sample Application, the following steps are taken to get а new account balance after writing а check:

FDV$RET (RI_AMTPAY_DSC, %ASCID'AMTPAY');
АMТРАY = VAL(DSC = RI_AMTPAY_DSC);
BALANCE = .BALANCE - .АMТРАY;
ТОТРАY = .TDTPAY + .АMТРАY;

FDV$PUT (STR$(.BALANCE), %ASCID'BALANCE');

In this example, the keyword macro VAL reads а string containing ASCII digits as а descriptor and returns the numeric value as а longword integer. The integer value of the variable АMТРАY can now be subtracted from the integer value of the variable BALANCE to produce а new value for BALANCE. АMТРАY can also be added to the integer value of the variable ТОТРАY to produce а new value for ТОТРАY.

After the data operations have been completed, the macro STR converts the longword integer value of the variable BALANCE to the corresponding ASCII decimal string descriptor. The value for the balance is displayed in the right-justified field 'BALANCE'. The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the ASCII decimal string are placed to the left of the rightmost digit. If output is longer than the field, FMS truncates on the left. (The Form Driver displays а data length error message (FDV$_DLN) only if you have set FMS Debug mode.)

For other conversion options, see the general conversion routines in the VAX-11 Run-Time Library Reference Manual.

The FMS Sample Application program (SAMPBLI.BLI) is part of the FMS distribution kit. When FMS is installed, SAMPBLI.BLI is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, SAMPBLI.BLI shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

S!    SAMPBLI.COM
$!
$!    Compile and link the BLISS version of the FMS V2 Sample Application
$!
$! The BLISS source files are:SAMPBLIBLI
                              FDVDEF.BLI
$!
$! SMPVECTOR.OBJ and SMPMEMRES.OBJ were produced by the FMS commands:
$!
$!   FMS/VECTOR/OUTPUT=SMPVECTOR SAMP.FLB
$!   FMS/MEMORY/OUTPUT=SMPMEMRES SAMP.FLB/FORM=(HELP_KEYS,HELP_MENU)
$!
$ BLISS SAMPBLI
$ LINK  SAMPBLI, FMS$EXAMPLES:SMPVECTOR, FMS$EXAMPLES:SMPMEMRES

In the С language, all out-of-line code sequences (such as procedures and subroutines) are called "functions." All С functions are external. The Form Driver routines are called from а С program using the standard С function reference syntax. For example:

fdv$wait ();

Calls the Form Driver routine fdv$wait and passes no parameters.

fdv$get (&_option, &terminator, $DESCR("OPTION"));

Calls the routine fdv$get and passes three parameters.

А status code is returned to the calling program at completion of all Form Driver function calls. To receive the returned status code from а Form Driver function, you activate the routine with а function reference. Note that this returns а standard VMS status code. For portability, other status mechanisms can also be used. (For more information, see the VAX-11 FMS Form Driver Reference Manual, Chapter 2.)

See Appendix A, VAX-11 FMS Form Driver Calls for а complete list of Form Driver calls. The calling sequence for each Form Driver routine, data access codes, data types, and passing mechanisms are presented in language-independent notation as specified by the VAX-11 Procedure Calling and Condition Handling Standard. For further detail about the VAX-11 Procedure Calling and Condition Handling Standard, refer to the VAX-11 Run-Time Library Reference Manual.

The parameter passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing parameters:

In С, all arguments are normally passed by value. FMS routines, however, expect arguments to be passed only by reference and by descriptor.

By reference specifies that the storage location of the argument is passed to the routine. FMS expects integer arguments to be passed by reference. From С, you can pass an integer to FMS by specifying its address in the argument list (using the & operator). Alternatively, you can pass а pointer whose current value is the address of the integer.

By descriptor specifies that the address of а descriptor of the argument is passed to the routine. FMS expects character strings and arrays to be passed by descriptor. (А descriptor is а data structure that specifies information about the argument.) The С language has no built-in facility for passing arguments by descriptor. Therefore, descriptors must be explicitly declared, and their fields filled in with the appropriate information, before they can be used to pass arguments to FMS routines. An argument can be passed by specifying the address of its descriptor in the argument list (using the & operator). Alternatively, you can pass а pointer whose current value is the address of the descriptor. See Section 4.5, “Descriptors” for more information on descriptors.

When the call syntax includes optional parameters and you do not wish to specify all of the information, you can use null arguments. Any optional parameter can be omitted to simplify your program. An address of 0 is assigned to each null argument. Optional parameters to the right of the last required parameter can simply be omitted from the call. In the following example, the fdv$getal call passes only the field terminator value:

fdv$getal (0, &terminator);

А descriptor is а VMS data structure that provides а mechanism for communicating data between independent procedures in an indirect, uniform, and controlled fashion. It contains all the information needed to characterize any given data item. FMS, as а VMS-layered product, uses descriptors, but the С language has no built-in facility for passing arguments by descriptor. To pass arguments by descriptor from а С program to an FMS routine, you must construct and manipulate your own descriptors.

The format and content of various descriptors is detailed in the VAX-11 Run-Time Library Reference Manual. As an aid to using descriptors in С, VAX-11 C provides an include file, DESCRIP.H, which contains the same information in the form of structure declarations and macro definitions. To access this information, simply include the following line in your program:

#include <descrip.h>

/* Include the canned descriptor declarations */
#include <descrip.h>
   .
   .
   .
/* Declare and initialize some data to be passed to FMS */
char form-name [6] = "FORM1";
   .
   .
   .
/* Declare and initialize a descriptor for the above data */
$DESCRIPTOR(dsc_form, form_name);
   .
   .
   .
/* Pass the data to FMS */
fdv$cdisp (&dsc_form);

struct dsc$descriptor_s
     {
     unsigned short    dsc$w_length;
     unsigned char     dsc$b_dtype;
     unsigned char     dsc$b_class;
     char              *dsc$a_pointer
     }

struct dsc$descriptor_s dsc_form = {sizeof(form_name)-1, 14, 1, form_name};

#include <descrip.h>
   .
   .
   .
/* Declare a descriptor, using the structure tag from DESCRIP.H */
struct dsc$descriptor_s dsc_form;
   .
   .
   .
/* Set the data type and descriptor class fields */
dsc_form,dsc$b_dtype=DSC$K-DTYPE-T;
dsc_form,dsc$b_class=DSC$K_CLASS-S;
   .
   .
   .
/*Set the string length and address fields */
dsc_form.dsc$w_length = 5;
dsc_form.dsc$a_pointer = FORM1'';
   .
   .
   .
/* Pass the address of the descriptor to FMs */
fdv$cdisp (&dsc_form);

С data types that are not recognized by FMS can be used in your С application program provided they are not passed to the Form Driver.

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by defining them to be:

In the Sample Application program, the tca, wksp, and mloc arguments are passed to several Form Driver routines. In the declaration section of the program, these arguments are defined to be integer array variables. You may alternatively define these variables to be character strings in your own application program. Use of character strings rather than longword integer arrays avoids the need to work with array descriptors which are considerably more complicated than string descriptors.

You can use macros to set up descriptors for the integer arrays passed by your program. The Sample Application program uses the following macro, created for the sample program, to declare longword integer arrays.

/*
* $DESCRIPTORA generates an array descriptor, and is used to describe
* the workspaces and terminal control area
*/

#define *DESCRIPTORA (name,array,type) struct dsc$descriptor_a \
name = { sizeof(type), DSC$K-DTYPE-L, DSC$K-CLASS-A,\
array,0,0,{0,0,0,0,0}, 1, sizeof array }

The following Sample Application program declarations establish names and storage for the integer array variables workspace, checkwksp, tcarea, and menu_form:

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be placed in а static or external storage area of your program. Note that this is not done in the Sample Application program. The sample program's structure protects the workspaces, terminal control areas, and run-time memory-resident form areas implicitly.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, the work­ space is allocated and the fdv$awksp routine is called. When the fdv$awksp routine is called, the first argument _workspace) specifies the area of memory to be used for your workspace. The second argument specifies an estimate of the workspace size (2000 bytes) that you will need to display the largest form in your application.

fdv$awksp (&_workspace, &2000);

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

User-created functions are useful to perform the conversions necessary to accommodate FMS requirements. The Sample Application creates several data conversion functions.

In the Sample Application, the following steps are taken to get а new account balance after writing а check:

In this example, the user-created function val reads the character string named regarray [lastregnum].ri_amtpay and returns the numeric value as а longword integer. The integer value is assigned to the variable amtpay. The integer value of the variable amtpay is subtracted from the integer value of the variable balance to produce а new balance. The value of amtpay is added to the integer value of the variable totpay to produce а new value for totpay.

After the data operations have been completed, the user-created function itoa converts the integer value of the variable balance to the corresponding ASCII character string descriptor. The value for balance is displayed in the right-justified field "BALANCE". The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the character expression are placed to the left of the rightmost digit. If output is longer than the field, FMS truncates on the left. (The Form Driver displays а data length error message (FDV$_DLN) only if you have set FMS Debug mode.)

For other conversion options, see the general conversion routines in the VAX-11 Run-Time Library Reference Manual.

The FMS Sample Application program (SAMPCC.C) is part of the FMS distribution kit. When FMS is installed, SAMPCC.C is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, SAMPCC.C shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

4.11.2. Command File for Building the Sample Application Program

The command file for building the Sample Application program includes all the information that you need to compile and link SAMPCC.C. When FMS is installed, the command file is placed in the directory FMS$EXAMPLES.

You can call any FMS routine as а subroutine or as а function. Syntax follows standard VAX-11 COBOL requirements.

CALL "FDV$WAIТ",

CALL "FDV$GET" USING ВY DESCRIPTOR D-MENU-OPTION
                     ВY REFERENCE TERMINATOR
                     ВY DESCRIPTOR N-MENU-OPTION,

CALL "FDV$GET" USING ВУ DESCRIPTOR D-MENU-OPTION
                     ВY REFERENCE TERMINATDR
                     ВY DESCRIPTOR N-MENU-OPTION
GIVING RETURN_STATUS,

The argument passing mechanism refers to the way in which data is passed to а called routine. VAX-11 COBOL has four methods for passing arguments:

FMS routines, however, expect arguments to be passed only by reference and by descriptor. (However, null arguments are passed by value. See Section 5.3, “Null Arguments”).

By reference specifies that the storage location of the argument is passed to the routine. FMS expects integers to be passed by reference, which is the COBOL default passing mechanism.

By descriptor specifies that the address of а descriptor data structure is passed to the called routine. FMS expects character strings and arrays to be passed by descriptor. But the COBOL default passing mechanism is by reference. To override the COBOL default, include ВУ DESCRIPТOR in the CALL statement's USING phrase. This will force the argument list entry to use the descriptor mechanism.

In the following example, the FDV$AWKSP call passes the data items WORKSPACE_SIZE and WORKSPACE to the FDV$AWKSP routine. The integer data item WORKSPACE_SIZE is passed by reference, as expected by FMS. Normally in COBOL а character string such as WORKSPACE would also be passed by reference. However, FMS expects to see а character string passed not as а single address, but as а block of storage passed by descriptor. Thus, the USING ВУ DESCRIPTOR phrase in the call statement is used to force the use of the descriptor mechanism to pass the character string WORKSPACE.

DATA DIVISION,
WORKING-STORAGE SECTION,
01    WORKSPACE       PIC X(12)         GLOBAL,
01    WORKSPACE_SIZE  PIC 9(5)   COMP   GLOBAL  VALUE  2000,

CALL "FDM$ AWKSP" USING BY DESCRIPTOR WORKSPACE
                        BY REFERENCE WORKSPACE_SIZE

When the call syntax includes optional arguments and you do not wish to specify all of the information, you can use null arguments. Each optional argument can be replaced by а zero to simplify the program. The zero functions as а placeholder for the null argument. Optional arguments to the right of the last required argument can simply be omitted from the call.

In the following example, the FDV$GETAL call passes only the field terminator value:

CALL "FDV$GETAL" USING BY VALUE       0,
                       BY REFERENCE TERMINATOR,

COBOL data types that are not recognized by FMS can be used in your COBOL application program provided they are not passed to the Form Driver.

FMS can generate skeleton declarations for the fields in FMS forms. Because the file generated is only а skeleton, you may need to edit the declarations. Create а COBOL library file using the following command:

FMS/DESCRIPTION/DECLARATIONS

At compile time, request the library file by means of the СОРУ statement in the data division of your program. Alternatively, you can use а text editor to add the declaration file to the data division of your program.

For а detailed description of the command and output associated with the COBOL library file, see the VAX-11 FMS Utilities Reference Manual. Note that these declarations are not used in the Sample Application program. The Sample Application program uses the FMS Version 1 equivalent.

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by defining them to be:

In the Sample Application program, the tca, wksp, and mloc arguments are passed to several Form Driver routines. These arguments are defined as character strings. You may alternatively define these variables to be integer arrays.

The following declarations establish names and storage for the character string variables TERM_CONTROL_AREA, WORKSPACE, CHECR_WORKSPACE, and MENU_FORM:

01      TERM_CONTROL_AREA  PIC X(12),
01      WORKSPACE          PIC X(12),
01      CHECK_WORKSPACE    PIC X(12),
01      MENU_FORM          PIC X(2000).

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be placed in а static storage area of your program. Note that this is not done in the Sample Application program. The sample program's structure protects the workspaces, terminal control areas, and run­time memory-resident form areas implicitly.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate, however, results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, а workspace is allocated and the FDV$AWKSP routine is called. When the FDV$AWKSP routine is called, the first argument (WORKSPACE) specifies the area of memory to be used for your workspace. The second argument (WORKSPACE-SIZE) specifies an estimate of the workspace size that you will need to display the largest form in your application.

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

Depending on the data types involved, you may need to impose data conversion operations on your variables. Any item with USAGE IS DISPLAУ can be used with FMS as а string. Data items defined to be PIC 9 are actually strings and can be used to make your data conversion less complex. They can be passed to FMS and can be used in arithmetic and logical operations. COBOL provides implicit data conversion in such cases. In cases where you have defined your variables to be PIC Х, you must do explicit data conversion through the use of the MOVE statement.

Regardless of how you define your strings, you may need to use the IN­ SPECT statement with the REPLACING ALL SPACES ВУ ZERO clause as part of any string-to-numeric conversion. Otherwise, you might not get the results you expect. Because the INSPECT statement is only used to replace blanks with zeros, INSPECT is unnecessary if you assign the Zero Fill attribute to the relevant fields. For more detail on assigning the Zero Fill attribute, see the VAX-11 FMS Utilities Reference Manual.

5.10.1. Data Conversion on PIC Х Variables

The following example from the Sample Application shows an explicit data conversion operation on variables defined to be PIC Х.

In this example, the COBOL statement MOVE transfers the data stored in the alphanumeric field D-REGIST-AMTPAY to the alphanumeric field ТMР_REG_ITEM_PАУ_АMТ. The INSPECT statement replaces the spaces in the alphanumeric field ТMР_REGJTEM_PAY_АMТ by zeros, preparing the data for conversion and transfer to an integer field. The MOVE statement again operates to transfer the data stored in ТMР_REG_ITEM_PAY_АMТ to the integer field NUM_REG_ ITEM_PAY_AMT. Now subtraction and addition operations can be performed on the integer data.

After the data operations have been completed, COBOL displays the value for the balance in а right-justified field N-CHECK-BALANC. The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the character expression are placed to the left of the rightmost digit. If output is longer than the field, FMS truncates on the left. The Form Driver displays а data length error message (FDV$_DLN) only if you have set FMS Debug mode.

For other conversion options, see the general conversion routines in the VAX-11 Run-Time Library Reference Manual.

5.10.2. Data Conversion on PIC 9 Variables

The following example from the Sample Application shows COBOL's implicit data conversion on variables defined to be PIC 9. Because the Form Editor assigned the Zero Fill attribute to CURRENТ_БALANCE, no INSPECT statement is necessary to replace spaces by zeros.

The FMS Sample Application program (SAMPCOB.COB) is part of the FMS distribution kit. When FMS is installed, SAMPCOB.COB is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, the Sample Application shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

5.11.2. Command File for Building the Sample Application Program

The command file for building the Sample Application program includes all the information that you need to compile and link SAMPCOB.COB. When FMS is installed, the command file is placed in the directory FMS$EXAMPLES.

You can call any FMS routine as а subroutine or as а function. Syntax follows standard VAX-11 FORTRAN requirements.

CALL FDV$WAIТ ()

CALL FDV$GET (OPTION, TERMINATOR, 'OPTION')

INTEGER*4 FDV$GET
INTEGER*4 RETURN_STATUS

RETURN_STATUS = FDV$GET (OPTION, TERMINATOR, 'OPTION')

The argument passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing arguments:

FMS routines, however, expect arguments to be passed only by reference and by descriptor.

By reference specifies that the storage location of the argument is passed to the routine. FMS expects integers to be passed by reference, which is also the FORTRAN default passing mechanism for integers.

By descriptor specifies that the address of а descriptor data structure is passed to the routine. FMS expects character strings and integer arrays to be passed by descriptor, which is the FORTRAN default passing mechanism for character strings (but not integer arrays).

Integer arrays require special treatment. Although the FORTRAN default passing mechanism for integer arrays is by reference, FMS has built-in functions for passing arguments when you wish to override FORTRAN default mechanisms. In this case, you can use the %DESCR function to force the argument list entry to use the descriptor mechanism. For example:

INTEGER*4 WORKSPACE (З)
CALL FDV$AWKSP (%DESCR(WORKSPACE), 2000)

When the call syntax includes optional arguments and you do not wish to specify all of the information, you can use null arguments. Any optional argument can be omitted to simplify your program. А comma functions as а placeholder for each null argument. Optional arguments to the right of the last specified argument can simply be omitted from the call. In the following example, the FDV$GETAL call passes only the field terminator value:

CALL FDV$GETAL (, FLDTRM)

FORTRAN data types that are not recognized by FMS can be used in your FORTRAN application program provided they are not passed to the Form Driver.

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by defining them to be:

In the Sample Application program, the tca, wksp, and mloc arguments are passed to several Form Driver routines. These arguments are defined as integer array variables. The following declarations establish names and storage for the integer array variables WORKSPACE, CHECKWKSP, ТСА, and MENU_FORM:

С     Data definitions

      INTEGER  WORKSPACE (3),    !General workspace
      1        CHECKWKSP (3),    !Check workspace
      2        TCA       (3),    !Terminal Control Area
      3        MENU_FORM (500),  !Storage for memory-resident form

You may alternatively declare these variables to be character strings in your own application program. You could then take advantage of FORTRAN's default passing mechanism for character strings (by descriptor). This would avoid the need to use %DESC to force the descriptor mechanism for passing integer arrays. Furthermore, you could then declare the actual storage area of character strings in bytes. The following statements declare and allocate space to the character strings WORKSPACE, CHECKWKSP, and ТСА:

CHARACTER*12 WORKSPACE
CHARACTER*12 CHECKWKSP
CHARACTER*12 ТСА

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be placed in а common storage area of your program. Note that this is not done in the Sample Application program. The sample program's structure protects the workspaces, terminal control areas, and run­time memory-resident form areas implicitly.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, workspace is allocated and the FDV$AWKSP routine is called. When the FDV$AWKSP routine is called, the first argument (WORKSPACE) specifies the area of memory to be used for your workspace. The second argument specifies an estimate of the workspace size that you will need to display the largest form in your application.

С     Data definitions
      INTEGER   WORKSPACE (3)        !General workspace
      1         CHECKWKSP (3)        !Check workspace

CALL FDV$AWKSP (%DESCR(CHECKWKSP), 2000)
CALL FDV$AWKSP (%DESCR(WORKSPACE), 2000)

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

In the Sample Application, the following steps are taken to get а new ac­ count balance after writing а check.

CALL FDV$RET (RI_AMTPAY, 'АMТРАY')
READ (RI_AMTPAY, '(I6)')
АMТРАУ BALANCE = BALANCE - АMТРАY
ТОТРАY = ТОТРАY + АMТРАY

WRITE (RI_BALANCE, '(I6)') BALANCE
CALL FDV$PUT (RI_BALANCE, BALANCE')

In this example, the FORTRAN internal file READ converts the character variable RI_AMTPАУ to the integer variable АMТРАY according to the format specification of 16. The integer value of the variable АMТРАY is subtracted from the integer value of the variable BALANCE to produce а new value for BALANCE. When converting ASCII to numeric, your application is assured а successful conversion if the field on the form was defined as numeric. This eliminates the need for an "ERR =" clause on the READ statement.

After the data operations have been completed, the FORTRAN internal file WRITE converts the integer variable BALANCE to а character expression RI_BALANCE. The value for the balance is displayed in the right-justified field 'BALANCE'. The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the character expression are placed to the left of the rightmost digit. If output is longer than the field, FMS truncates on the left. The Form Driver displays а data length error message (FDV$_DLN) only if you have set FMS Debug mode.

For other data conversion options, see the general conversion routines in the VAX-11 Run-Time Library Reference Manual.

The FMS Sample Application program (SAMPFOR.FOR) is part of the FMS distribution kit. When FMS is installed, SAMPFOR.FOR is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, SAMPFOR.FOR shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

6.10.2. Command File for Building the Sample Application Program

The command file for building the Sample Application program includes all the information that you need to compile and link SAMPFOR.FOR. When FMS is installed, the command file is placed in the directory FMS$EXAMPLES.

You can call any FMS routine as а procedure or as а function. Syntax follows standard VAX-11 PASCAL requirements.

FDV$WAIТ ();

FDV$GET (FLDVAL := Option, FLDTRM := Terminator, FLDNAM := 'OPТION'

STATUS_RETURN = FDV$GET (ОРТION, TERMINATOR, 'OPTION');

The parameter passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing parameters:

FMS routines, however, expect parameters to be passed only by reference and by descriptor.

By reference specifies that the storage location of the parameter is passed to the routine. FMS expects integers to be passed by reference which is the PASCAL default passing mechanism for all data types.

By descriptor specifies that the address of а descriptor data structure is passed to the called routine. FMS expects character strings and arrays to be passed by descriptor. The default passing mechanism for conformant arrays (those that assume the characteristics of their actual arguments) is by descriptor. However, the PASCAL default passing mechanism for character strings is by reference. Consequently, the [CLASS_SJ attribute is used to force use of the [CLASS_SJ string descriptor mechanism for passing character strings to the FMS routine. For example:

When the call syntax includes optional parameters and you do not wish to specify all of the information, you сап use null arguments. Each optional parameter can be omitted to simplify your program. Optional parameters to the right of the last required parameter can simply be omitted from the call. In the following example, the FDV$GETAL call passes only the field terminator value:

FDV$GETAL (FLDTRM := Terminator);

РASCAL has two ways to specify null arguments. One approach is to use non-positional syntax. You use named parameters and do not reference the omitted parameters. The other approach is to use positional parameters and represent null parameters by а comma. Thus, the following two statements are equivalent:

FDV$GETAL (FLDTRM := Terminator)
FDV$GETAL (Terminator,,,)

All optional parameters must be declared with а default value (usually %IMMED 0).

VAX-11 РASCAL supports null arguments by allowing you to supply а default immediate value of zero in the declaration of the routine to which the null argument is to be passed. For example, in the declaration of the function FDV$ATERM, а default immediate value of zero is supplied to the parameters size, channel, and terminal.

[ASYNCHRONOUS] FUNCTION FDV$ATERM (
    VAR tca : [VOLATILE] ARRAY [$11..$ui : INTEGER] OF INTEGER;
    size : INTEGER := %IMMED 0;
    channel : INTEGER := %IMMED 0;
    terminal : INTEGER := %IMMED 0) : INTEGER; EXTERNAL

A call to the FDV$ATERM routine declared above follows:

FDV$ATERM (terminal, 12, 1,);

The following call is equivalent but it leaves off the trailing comma:

FDV$ATERM (terminal, 12, 1);

The most difficult part of calling external routines from PASCAL is defining the entry points. Every entry point used in а РASCAL program must be declared with all its parameters and their types.

It is extremely important to have complete, correct definitions of all the entry points and their arguments. Your program will not compile if the number, data types, and uses of arguments in а call do not agree with their declarations. The include file FDVDEF.PAS contains definitions for the Form Driver constants and entry points. To access the Form Driver entry points, your program must inherit the precompiled environment file FDVDEF.PEN. The following steps can be performed:

Many calls to FMS have а variable number of arguments. If you use the file FDVDEF.PEN, you do not have to worry about these variations in specified arguments because FDVDEF.PEN has the entry points for the Form Driver defined.

PASCAL data types that are not recognized by FMS can be used in your PASCAL application program provided they are not passed to the Form Driver.

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by declaring them to be:

In the Sample Application program, the tca, wksp, and mloc arguments are passed to several Form Driver routines. These arguments are declared to be integer array variables. You may alternatively declare these variables to be character strings. (The strings can be static or varying length but must be extended to the proper length.) If you declare these variables to be character strings, you need to redefine all of the entry points that reference terminal control area, workspace, and memory location. Otherwise, you will get compile errors.

The following declarations establish names and storage for the integer array variables Workspace, Checkwksp, Тса, and Menu_form:

VAR  Workspace : [VOLATILE] ARRAY [1..]3] OF INTEGER; { General workspace }
     Checkwksp : [VOLATILE] ARRAY [1..]3] OF INTEGER; { Check workspace }
     Tca : [VOLATILE] ARRAY [1..3] OF INTEGER;        { Term Control Area }
     Menu_form : [VOLATILE] ARRAY [1..500] OF INTEGER;
                                       { Storage for memory-resident forms }

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be declared with the VOLATILE attribute.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage space based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver will allocate more space automatically, but performance may be affected. An adequate estimate results in more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, workspace is allocated and the FDV$AWKSP routine is called. When the FDV$AWKSP routine is called, the first argument (WORKSPACE) specifies the area of memory to be used for your workspace. In the declaration section of your program, 12 bytes (3 longwords) are allocated to workspace storage. The second argument in the FDV$AWKSP call specifies an estimate of the workspace size (2000 bytes) that you will need to display the largest form in your application.

VAR Workspace : [VOLATILE] ARRAY [l..3] OF INTEGER;
FDV$AWSKP (WORKSPACE,2000);

FMS uses only ASCII character strings to display data. All information displayed on the terminal screen, and all information received from the terminal operator, will be represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to

numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

In the Sample Application, the following steps are taken to get а new account balance after writing а check:

In this example, the READV procedure is used to convert the character string expression Amtpay to an integer variable Amount_paid, which is used to hold the data item's value. The integer value of the variable Amount_paid is subtracted from the integer value of the variable Current_Balance to produce а new value for Current_Balance. The value of Amount_paid is also added to the integer value of the variable TotalPayment to produce а new value for TotalPayment.

After the data operations have been completed, the function Integer_to_Text converts the integer value of the variable Current_Balance to the corresponding ASCII character expression. (Note that the function Integer_to_Text is not а PASCAL predeclared function; it is а user-defined function created for the Sample Application program.) After the value for balance has been converted to а character expression, it is displayed in а right-justified field 'BALANCE.' The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the character expression are placed to the left of the rightmost digit. If output is longer than the field, FMS truncates on the left. (The Form Driver displays а data length error message (FDV$..DLN) only if you have set FMS Debug mode.)

The FMS Sample Application program (SAMPPAS.PAS) is part of the FMS distribution kit. When FMS is installed, SAMPPAS.PAS is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, the Sample Application shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

7.11.2. Command File for Building the Sample Application Program

The command file for building the Sample Application program includes all the information that you need to compile and link SAMPPAS.PAS. When FMS is installed, the command file is placed in the directory FMS$EXAMPLES.

You can call any FMS routine as а subroutine or as а function. Syntax follows standard VAX-11 PL/I requirements.

CALL FDV$WAIТ;

CALL FDV$GET (OPTION, TERMINATOR, 'OPTION');

DCL FDV$GET ENTRY (CHAR (*), FIXED BIN (31), CHAR (*), FIXED BIN (31)

    RETURNS (FIXED BIN (31)) OPTIONS (VARIABLE);

DCL STATUS FIXED BIN (31);

STATUS = FDV$GET (OPTION, TERMINATOR, 'OPTION');

The argument passing mechanism refers to the way in which data is passed to а called routine. The VAX-11 Procedure Calling Standard has three methods for passing arguments:

FMS routines, however, expect arguments to be passed only by reference and by descriptor.

By reference specifies that the storage location of the argument is passed to the routine. FMS expects integers to be passed by reference, which is the PL/I default passing mechanism for integers.

By descriptor specifies that the address of а descriptor data structure is passed to the called routine. FMS expects character strings and arrays to be passed by descriptor. PL/I automatically passes character strings and arrays by descriptor if the parameter descriptors show а variable extent, as they do in the FMS include files FDVDEFCAL.PLI and FDVDEFFNC.PLI. Generally (in the EXTERNAL ENTRY declaration for FMS procedures), specify all character strings and integer arrays in the parameter list with (*). This will force PL/I to always pass arguments by descriptor, which is what FMS expects.

When the call syntax includes optional arguments and you do not wish to specify all of the information, you can use null arguments. Any optional arguments can be omitted to simplify your program. А comma functions as а placeholder for each null argument. Optional arguments to the right of the last required argument can simply be omitted from the call. In the following example, the FDV$GETAL call passes only the field terminator value:

CALL FOV$GETAL ( ,FLDTRM);

The most difficult part of calling external routines from PL/I is defining the entry points. Every entry point used in а PL/I program must be declared with all its parameters and their types.

It is extremely important to have complete, correct definitions of all the entry points and their arguments. Your program may get warning mes­ sages if the number, data types, and uses of arguments in а call do not agree with their declarations. The include files FDVDEFCAL.PLI and FDVDEFFNC.PLI contain definitions for the entry points for the Form Driver. FDVDEFCAL.PLI is the file for procedure calls. FDVDEFFNC.PLI is the file for function calls.

Many calls to FMS have а variable number of arguments. If you use the include file FDVDEFCAL.PLI or FDVDEFFNC.PLI, you do not have to worry about these variations in specified arguments because these include files have the entry points for the Form Driver defined.

If you do whole form processing with the FDV$GETAL, FDV$PUTAL, and FDV$RETAL routines, you can use the FMS/DESCRIPTION/DECLARATIONS command to produce а file of declarations describing the transferred data. Although these declarations are not directly usable in your PL/I program, they closely resemble PL/I syntax. You can edit them and include them in your application program.

PL/I data types that are not recognized by FMS can be used in your PL/I application program provided they are not passed to the Form Driver. Using the Form Driver entry points correctly declared in your program, PL/I converts input arguments of non-FMS data type to arguments of the correct type by creating dummy arguments. However, you will not be given access to the values returned by the Form Driver to the output arguments. To allow non-FMS data types in your program to interact with FMS, use the PL/I conversion routines explicitly (see the VAX-11 PL/I document set).

One-dimensional arrays are structures that can be used in FMS for the following arguments:

You must provide FMS with storage space for these arguments. You can do that by defining them to be:

In the Sample Application program, the tca, wksp, and mloc arguments are passed to several Form Driver routines. These arguments are defined as integer array variables. You may alternatively define these arguments to be character strings. If you declare these variables to be character strings, you need to redefine all of the entry points that reference terminal control area, workspace, and memory location. Otherwise, you will get compile errors.

The following declarations establish names and storage for the integer array variables WORKSPACE, CHECKWKSP, ТСА, and MENU_FORM:

DCL  WORKSPACE (3) FIXED BIN (31);   /* General workspace     */
DCL  CHECKWKSP (3) FIXED BIN (31);   /* Check workspace       */
DCL  TCA       (3) FIXED BIN (31);   /* Terminal Control Area */
DCL  MENU_FORM (500) FIXED BIN (31); /* Storage for memory-resident form*/

The FMS workspace, terminal control area, and run-time memory-resident form area variables are character strings or longword integer arrays. These variables should be declared EXTERNAL. Note that this is not done in the Sample Application program. The sample program's structure protects the workspaces, terminal control areas, and run-time memory-resident form areas implicitly.

The Form Driver needs 12 bytes to associate user information about each workspace and terminal control area. The allocation for а run-time memory-resident form area must be the size of the form. The space for all of these variables is allocated by your application program. Note that FMS uses only 12 bytes of space for the workspace and terminal control area allocation. Any allocation greater than 12 bytes is wasted. You declare your workspace, terminal control area, and run-time memory-resident form area only once. FMS remembers their addresses after the addresses have been initially passed to the Form Driver.

For each workspace, the Form Driver also allocates an additional amount of storage based on your estimate of the amount of memory needed to store your largest form. If your estimate is too small, the Form Driver allocates more space automatically, but performance may be affected. An adequate estimate results in а more efficient operation of the Form Driver. You can use the FMS/DIRECTORY/FULL command to find out how much space to allocate.

In the following example from the Sample Application program, workspace is allocated and the FDV$AWKSP call is issued. When the FDV$AWKSP routine is called, the first argument (WORKSPACE) specifies the area of memory to be used for your workspace. The second argument specifies an estimate of the workspace size (2000 bytes) that you will need to display the largest form in your application.

DCL WORKSPACE (3) FIXED BIN (31);    */ General workspace */

CALL FDV$AWKSP (WORKSPACE, 2000);

FMS uses only ASCII character strings to display data. АН information displayed on the terminal screen, and all information received from the terminal operator, is represented as ASCII field values. Any manipulation of numeric data requires conversion of ASCII character strings to numeric data, and conversion of numeric data back to ASCII character strings. In the following discussion of conversion routines, you should assume that the receiving data type can support the largest number that is likely to be generated.

In the Sample Application, the following steps are taken to get а new ac­ count balance after writing а check:

In this example, the PL/I FIXED function is used to convert the string expression REGARRAY.AMTPAY(LASTREGNUM) to а fixed-point integer variable with а specified number of binary digits (31) used to hold the data item's value. The integer value of АMТРАY is subtracted from the integer value of BALANCE to produce а new value for BALANCE. The value of АMТРАY is also added to the integer value of ТОТРАY to produce а new value for ТОТРАY.

After the data operations have been completed, an integer-to-ASCII character string conversion is accomplished. Using an assignment to а picture variable, the user-created CENТS function is used to convert the integer variable BALANCE to an ASCII character expression BALANCE. The value for the balance is displayed in а right-justified field 'BALANCE'. The rightmost digit from the program is displayed in the field's rightmost character position. The remaining digits of the character expression are placed to the left of the rightmost digit. If input is longer than the field, FMS truncates on the left. (The Form Driver displays а data length error message (FDV$_DLN) only if you have set FMS Debug mode.)

Note that in this example the output goes to а field with а decimal point field-marker character. In the presence of а decimal point field marker, the Form Driver creates strange-looking output for single-digit data items. The output will be а period followed by а space and then digit rather than .01, for example. In the above example, the assignment to а picture variable is used to prevent this kind of unconventional output.

The PL/I built-in function CHARACTER converts а number to а character string with one or two leading blanks (see the VAX-11 PL/I documentation for details). If you display this string in а left-justified field, you must take these leading blanks into consideration. Your program can use the CHAR­ ACTER function for data conversion operations if field markers will not create а confusing appearance.

For other conversion options, see the general conversion routines in the VAX-11 Run-Time Library Reference Manual.

The FMS Sample Application program (SAMPPLI.PLI) is part of the FMS distribution kit. When FMS is installed, SAMPPLI.PLI is placed in the directory FMS$EXAMPLES. Designed to be а demonstration program and learning tool, SAMPPLI.PLI shows most of the features provided by FMS. The entire Sample Application program appears at the end of this chapter.

8.12.2. Command File for Building the Sample Application Program

The command file for building the Sample Application program includes all the information that you need to compile and link SAMPPLI.PLI. When FMS is installed, the command file is placed in the directory FMS$EXAMPLES.