DYNFORM-Callable interface for IFD files

DYNFORM accepts the name of an IFD file and handles all functions for
processing the screen.

Format

DYNFORM

ifd_file

output _file
form _file
return _code
user _key
callback _vector
reserved _ssdt

RETURNS

none

Arguments

ifd_file

The name of the IFD file to process.

output_file

The name of the output list data file. Overrides the value specified by
SET OUTPUT.

list_file

The name of the LSTPRC form file for "print" function. Overrides the
value specified by SET FORM.

return_code

Status value returned by DYNFORM. Y = success, E = errors occurred in
IFD file

user_key

The numeric value of the key press by the user to exit the routine.
Keys are numbered consecutively from 01 thru 13. F6 = 01, F7 = 02, etc.

callback_vector

Address of callback vector to make available to IFD file for help or
validation callbacks. If a callback vector is not supplied then zero
must be pasted by value. See text.

reserved_ssdt

Reserved for use by SSDT only. Must contain an address of a longword
containing zero.

Description

DYNFORM handles all parsing of the IFD file, user prompting, saving and restoring of data files. Control is not returned from DYNFORM until the use press a function key that causes the screen to exit (e.g. exit, cancel, execute).

The callback vector contains a list of routine names and the corresponding addresses. These routines will be made available to the IFD file for callbacks. The callback vector must take the following format:

 
01   CALLBACK-VECTOR. 
    03  CALLBACK-COUNT  PIC S9(9) COMP. 
    03  CALLBACKS  OCCURS 0 TO 128 TIMES DEPENDING ON CALLBACK-COUNT. 
        05  ROUTINE        PIC X(32). 
        05  ADDRESS        PIC S9(9) COMP. 
 

Where "ROUTINE" contains the name of the module and "ADDRESS" contains the VMS entry point address of the routine.

Example

The following is a sample call for an IFD file containing two callbacks

 
WORKING-STORAGE SECTION. 
01   DYNFORM-PARMS. 
    03   DYNFORM-IFD-FILE              PIC X(255) VALUE SPACE. 
    03   DYNFORM-OUTPUT-FILE           PIC X(255) VALUE SPACE. 
    03   DYNFORM-FORM-FILE             PIC X(255) VALUE SPACE. 
    03   DYNFORM-RETURN-CODE           PIC XX VALUE SPACE. 
    03   DYNFORM-USER-KEY              PIC 9(2) VALUE ZERO. 
    03   DYNFORM-RESERVED              PIC S9(9) COMP VALUE ZERO. 
 
01   DYNFORM-CALLBACK-ITEMS. 
    03  PIC S9(9) COMP VALUE 2. 
    03  PIC X(32)       VALUE "IFD_DATE_RANGE". 
    03  PIC S9(9) COMP  VALUE EXTERNAL IFD_DATE_RANGE. 
    03  PIC X(32)       VALUE "IFD_VEND_NUMVAL". 
    03  PIC S9(9) COMP  VALUE EXTERNAL IFD_VEND_NUMVAL. 
01   DYNFORM-CALLBACK-VECTOR 
    REDEFINES DYNFORM-CALLBACK-ITEMS. 
    03  DYNFORM-CALLBACK-COUNT     PIC S9(9). 
    03  DYNFORM-CALLBACKS  OCCURS 2 TIMES. 
        05  DYNFORM-ROUTINE        PIC X(32). 
        05  DYNFORM-ADDRESS        PIC S9(9) COMP. 
 
PROCEDURE DIVISION. 
 
. 
. 
. 
 
CALL-SAMPLE-IFD SECTION. 
CALL-SAMPLE-IFD-01. 
 
    MOVE "OECN$BUD:SAMPLE" TO DYNFORM-IFD-FILE. 
    CALL "DYNFORM" USING DYNFORM-IFD-FILE 
                         DYNFORM-OUTPUT-FILE 
                         DYNFORM-FORM-FILE 
                         DYNFORM-RETURN-CODE 
                         DYNFORM-USER-KEY 
                         DYNFORM-CALLBACK-VECTOR 
                         DYNFORM-RESERVED. 
    
      

The above example, calls DYNFORM to process the file OECN$BUD:SAMPLE.IFD. The output file will default to OECN$OUT:SAMPLE.DAT unless specfied by the .IFD file.

BATPARMS-Parses parameter files

BATPARMS reads a standard parameter file created by DYNFORM and returns
one token per call.

Format

BATPARMS

file

function
token
value
status
description

RETURNS

none

Arguments

file

File name of parameter file to parse. Must remain unchanged between
calls for each token. Otherwise, the new file will be opened. Default
file spec is OECN$OUT:

function

Function to perform. Must contain one of the following:

token

Name of returned token.

value

Data value for returned token.

status

Return status:

Description

Description of token value, from comments in parameter file.

Description

When called with the "Next" function BATPARMS reads and parses the specified parameter file on the first call (or whenever the file name changes between calls). It then returns the first token and associated value. On each subsequent call, it returns the next token until all tokens are returned.

Between calls using the "Next" function, BATPARMS can be called with the "Mark" function to request that BATPARMS mark the current token for later recall. This allows the calling program to indicate which tokens it will want recalled later, without storing the tokens itself. This might be used, for instance, to mark tokens which will be printed later on an options page.

If any tokens have been marked, then BATPARMS can be called using the "Retrieve" function to return each marked token.

h3. Examples

 WORKING-STORAGE SECTION. 
 01   BATPARMS-PARAMETERS. 
    03  BATPARMS-FILE       PIC X(255). 
    03  BATPARMS-FUNCTION  PIC X(01) VALUE "N". 
        88 BATPARMS-NEXT              VALUE "N". 
        88 BATPARMS-MARK-TOKEN        VALUE "M". 
        88 BATPARMS-NEXT-MARKED    VALUE "R". 
    03  BATPARMS-TOKEN      PIC X(32). 
    03  BATPARMS-DATA       PIC X(80). 
    03  BATPARMS-DESC       PIC X(80). 
    03  BATPARMS-FLAG       PIC X(01). 
        88  BATPARMS-OK         VALUE "Y". 
        88  BATPARMS-DONE       VALUE "N". 
        88  BATPARMS-ERROR      VALUE "E". 
 
    . 
    . 
    . 
 
PROCEDURE DIVISION. 
. 
. 
. 
GET-PARMS SECTION. 
GET-PARMS-01. 
 + 
 Get name of parameter file from foreign command line. 
 - 
    CALL "lib$get_foreign" USING 
         BY DESCRIPTOR BATPARMS-FILE. 
    PERFORM BATPARMS-NEXT. 
    PERFORM UNTIL NOT BATPARMS-OK 
        EVALUATE BATPARMS-TOKEN 
            WHEN  "<SORT>"  MOVE BATPARMS-DATA TO WS-SORT 
            WHEN  "<FILENAME>" MOVE BATPARMS-DATA TO WS-FILE 
                . 
                . 
                . 
        END-EVALUATE 
        PERFORM BATPARMS-NEXT 
    END-PERFORM. 
 
 
BATPARMS-NEXT SECTION. 
BATPARMS-NEXT-01. 
    SET BATPARMS-NEXT TO TRUE. 
    CALL "BATPARMS" USING   BATPARMS-FILE 
                            BATPARMS-FUNCTION 
                            BATPARMS-TOKEN 
                            BATPARMS-DATA 
                            BATPARMS-FLAG 
                            BATPARMS-DESC. 
    IF BATPARMS-FLAG = "E" 
        DISPLAY "Missing or empty parameter file" 
        STOP RUN. 
 
      

The above example, gets the parameter file from the foreign command line (assuming there is only one parameter) and passes it to BATPARMS. BATPARMS is called repeatedly to return each token name and sets the programs local storage. Note that the program does not assume the tokens are in any particular order and does not produce errors for tokens it does not recognize.