Child pages
  • DYNFORM Callable Interface

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin
Panel
Table of Contents

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

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

255 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

The name of the IFD file to process.

output_file

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

255 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

list_file

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

255 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

return_code

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

2 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

write

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

user_key

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

2 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

write

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

varying array

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

varying array

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

varying array

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

varying array

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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:

Code Block
 
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.

Info

SSDT programmers must use DYNFORM.F to create the calling interface to DYNFORM and the callback vector.

Example

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

HTML Table
border0
width75%
Table Row (tr)
Table Head (th)

Table Row (tr)
Table Cell (td)
Code Block
 
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

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

255 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

1 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

read

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

Function to perform. Must contain one of the following:

HTML Table
border3
width75%
Table Row (tr)
Table Cell (td)

N

Table Cell (td)

Return next token

Table Row (tr)
Table Cell (td)

M

Table Cell (td)

Mark current token

Table Row (tr)
Table Cell (td)

R

Table Cell (td)

Retrieve next marked token

token

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

32 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

write

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

Name of returned token.

value

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

80 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

write

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

Data value for returned token.

status

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

1 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

write

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

Return status:

HTML Table
border3
width75%
Table Row (tr)
Table Cell (td)

Y

Table Cell (td)

Successful, token returned

Table Row (tr)
Table Cell (td)

N

Table Cell (td)

Unsucessful, no more tokens

Table Row (tr)
Table Cell (td)

E

Table Cell (td)

Error, parameter file not found or empty

Description

HTML Table
Table Row (tr)
Table Cell (td)

VMS usage:

Table Cell (td)

fixed length string

Table Row (tr)
Table Cell (td)

type:

Table Cell (td)

80 character string

Table Row (tr)
Table Cell (td)

access:

Table Cell (td)

write

Table Row (tr)
Table Cell (td)

mechanism:

Table Cell (td)

by reference

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

HTML Table
border0
width75%
Table Row (tr)
Table Head (th)
#1
Table Row (tr)
Table Cell (td)
Code Block
 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.