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
VMS usage: |
fixed length string |
type: |
255 character string |
access: |
read |
mechanism: |
by reference |
The name of the IFD file to process.
output_file
VMS usage: |
fixed length string |
type: |
255 character string |
access: |
read |
mechanism: |
by reference |
The name of the output list data file. Overrides the value specified by
SET OUTPUT.
list_file
VMS usage: |
fixed length string |
type: |
255 character string |
access: |
read |
mechanism: |
by reference |
The name of the LSTPRC form file for "print" function. Overrides the
value specified by SET FORM.
return_code
VMS usage: |
fixed length string |
type: |
2 character string |
access: |
write |
mechanism: |
by reference |
Status value returned by DYNFORM. Y = success, E = errors occurred in
IFD file
user_key
VMS usage: |
fixed length string |
type: |
2 character string |
access: |
write |
mechanism: |
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
VMS usage: |
varying array |
type: |
varying array |
access: |
read |
mechanism: |
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
VMS usage: |
varying array |
type: |
varying array |
access: |
read |
mechanism: |
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:
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.
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
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
VMS usage: |
fixed length string |
type: |
255 character string |
access: |
read |
mechanism: |
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
VMS usage: |
fixed length string |
type: |
1 character string |
access: |
read |
mechanism: |
by reference |
Function to perform. Must contain one of the following:
N |
Return next token |
M |
Mark current token |
R |
Retrieve next marked token |
token
VMS usage: |
fixed length string |
type: |
32 character string |
access: |
write |
mechanism: |
by reference |
Name of returned token.
value
VMS usage: |
fixed length string |
type: |
80 character string |
access: |
write |
mechanism: |
by reference |
Data value for returned token.
status
VMS usage: |
fixed length string |
type: |
1 character string |
access: |
write |
mechanism: |
by reference |
Return status:
Y |
Successful, token returned |
N |
Unsucessful, no more tokens |
E |
Error, parameter file not found or empty |
Description
VMS usage: |
fixed length string |
type: |
80 character string |
access: |
write |
mechanism: |
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
#1 |
---|
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.