| Author | : | A J Marston |
| Date Created | : | September, 1984 |
| Date Revised | : | February, 1993 |
| Version | : | 01.010.009 |
A macro (or pre-compiler directive) is a method of predefining a block of code, whether a single statement or a group of statements, so that the entire block can be incorporated into the program at compile time with a single statement in the source file. It is also possible to define variables within the macro, with particular values being supplied on the source statement. When the source is compiled each macro reference will be "expanded" into the relevant source statements, and any variables will be replaced by the specified parameter values.
A macro is defined with the "$DEFINE %name = ?" statement, which is followed by the contents of that macro and terminated by the # character (an alternative character may be specified if required).
The macro can be referenced anywhere in the program source by entering %name in the relevant place. Each macro must be defined in the source code before it can be referenced. If the macro requires parameters these must be supplied on the source statement in the specified sequence, as follows:
%NAME(parm1#,parm2#,parm3#,parm4#.......)
If the list of parameters is too large to fit on a single line then it should be split as follows:
%NAME(parameter1#,parameter2#,parameter3# ,parameter4#).
Note that each parameter value includes all the characters, including spaces, that occur between the delimiters "," and "#".
All the following macros (unless specified otherwise) are contained in a file called STDMACRO which can be incorporated into the program at compile time by specifying the $INCLUDE STDMACRO statement at the start of the program.
Where the first parameter is designated as Para# it signifies the paragraph name where that macro is being referenced within the program. If the code within the macro detects an error control will be passed to the standard UERROR routine which will include the paragraph name on the diagnostic report before it aborts.
Some of the following macros may call a subroutine to perform the actual processing - please refer to Library of Standard Utilities for more information regarding these routines.
This is for the IDENTIFICATION DIVISION.
This is for the ENVIRONMENT DIVISION. If the compiler switch X1 is set ON then the SOURCE-COMPUTER statement will include the WITH DEBUGGING MODE clause. Any subsequent statements containing a "D" in column 7 will then be compiled into code instead of being left as a comment.
This is for batch programs, and initialises the contents of the COMMON-LINKAGE area.
If the compiler switch X1 is ON this will generate a series of debugging statements in the DECLARATIVES SECTION. If the program is then run with the ;PARM=1 option it will display a line on the $STDLIST device each time it passes through a section/paragraph while it is executing the code.
This macro is contained within a separate additional file for each application as it contains hard-coded values that are unique for each application. It enables the program details to be included in the version number printing mechanism.
Load and initialise a new form.
Display current form and accept user's response. If a value is loaded into VIEW-FIELD-NAME then the cursor will be positioned on that field. If the ENTER key is pressed the VFIELDEDITS and VFINISHFORM processing will be performed. If the PRINT key is pressed the current screen contents will be printed. If the HELP key is pressed a help screen will be displayed.
Display current form and accept user's response (function keys 1-8 only, the ENTER key is not allowed).
Transfer current data buffer into the program's working storage area.
Transfer new data buffer to the screen area before it is displayed.
Similar to VPUTBUFFER, but for a single field only.
Set the error flag for a field on the current form. The field name must be loaded into VIEW-FIELD-NAME, and the error message must be loaded into VIEW-WINDOW.
After successful validation this allows the user to confirm that the current data is correct (by pressing the specified function key) and should be processed. If the ENTER key is pressed the entire screen contents must be revalidated.
Allows the user to continue or cancel the deletion.
Displays a message on the window line with the blink option set while some processing takes place (eg: a database update). The keyboard is locked until the next user response is required.
Captures the current screen contents prior to a call to VGETBUFFER by simulating the ENTER key.
Same as %VAUTOREAD but includes calls to VFIELDEDITS and VFINISHFORM.
Allows the characteristics (enhancement, field type, data type) of a field on the current form to be changed without the need for loading a new form. Please refer to Library of Standard Utilities for more details.
Allows the user to select the next transaction by pressing a function key within the current transaction instead of having to exit back to a menu screen. If no selection is made the program should reprompt for input, otherwise it should exit. Please refer to Library of Standard Utilities for more details.
This dumps the current screen contents to a temporary disk file before the program exits back to the menu. See also %USCREENIN.
This will reload the previous screen contents (created by %USCREENOUT) back into the program's working storage area when it is resumed. Please refer to Library of Standard Utilities for more details.
It should not be necessary to reference any of the following macros as they are used within the standard software (MENU, MENUSON and UVPLUS). They are included here for documentation purposes only.
Calls UERROR if VIEW-STATUS is unequal to zero. This is included in every macro for a VPLUS intrinsic.
This opens the terminal (VDU) device.
This opens the VPLUS formsfile identified by #Name.
Calls both VOPENTERM and VOPENFORMF.
This closes the terminal (VDU) device.
Closes the current formsfile.
Calls both VCLOSETERM and VCLOSEFORM.
Load key labels into VPLUS area so that they can be displayed with the next %ACCEPTENTER or %ACCEPTFUNCTION.
Switches off block-mode processing without closing the terminal.
Returns to block-mode processing.
Calls UERROR if IMAGE-COND not = zero. This is included in every IMAGE macro.
Opens the database in mode 1.
Opens the database in mode 5.
Determines if IMAGE Transaction Logging has been turned on.
Close the entire database.
Reset dataset pointer prior to a serial read.
Finds a particular chain of entries on a detail dataset.
Finds a chain on a detail dataset and reads the first record only.
Finds a chain on a detail dataset and reads the last record only.
Re-read current record.
Forward serial read.
Backward serial read.
Directed read. Argument is the record pointer.
Forward chained read.
Backward chained read.
Same as %DBGET5, but does not abort if IMAGE-BROKEN-CHAIN is found.
Same as %DBGET6, but does not abort if IMAGE-BROKEN-CHAIN is found.
Calculated read.
Prime calculated read.
Sets an entry in the lock descriptor array, which can contain up to 10 entries. The "number" parameter is used both as an index into the array, and the counter for the total number of entries within the array, therefore entries must be defined in strict ascending sequence. The locks will not actually be applied until the %DBLOCK macro is called.
Lock the database using the contents of the lock descriptor array, which is defined using the %SETLOCK macro. This uses subprogram UDBLOCK.
Release all locks on the database.
Identifies the start of a logical transaction (used only if IMAGE Transaction Logging is turned on).
Allows text to be added to the IMAGE transaction log file (used only if IMAGE Transaction Logging is turned on).
Identifies the end of a logical transaction (used only if IMAGE Transaction Logging is turned on).
Adds a new record to the dataset.
Updates the current record on the dataset.
Deletes the current record from the dataset.
Calculates the remaining capacity on the dataset and puts the result in IMAGE-SPARE-CAP.
This will re-read a master record into a secondary area and compare it with the previous contents. To be used before updating. Requires the statement "COPY COMPARE IN STANDARD" to define the secondary area in the program's working storage section. VEDIT-ERRORS will be set if the compare fails, and an error message will be loaded into VIEW-WINDOW.
This will re-read a detail record into a secondary area and compare it with the previous contents. To be used before updating. Requires the statement "COPY COMPARE IN STANDARD" to define the secondary area in the program's working storage section. VEDIT-ERRORS will be set if the compare fails, and an error message will be loaded into VIEW-WINDOW.
Calls UERROR if KSAM-STATUS not = zero. This is included in every KSAM macro.
Position pointer prior to a sequential read.
Sequential read.
Lock the entire file.
Delete the current record.
Unlock the file.
Read a record using the key value supplied.
Update the current record.
Add a new record.
Open the file for exclusive access.
Open the file for shared access.
Close the file.
Changes date from DD/MM/YY to CCYYMMDD.
Changes date from MM/DD/YY to CCYYMMDD.
Changes date from CCYYMMDD to DD/MM/YY.
Changes date from CCYYMMDD to DDMMMYY (eg: 28JAN91).
Calls UERROR if UDATE-STATUS is unequal to zero.
Convert date from CCYYMMDD to DDDDDDDDD, with result in JULIAN-DAYS. If UDATE-STATUS <> zero VIEW-WINDOW will contain an error message. This also sets UDATE-DAY-OF-WEEK to indicate the day name.
Convert date from DDDDDDDDD (JULIAN-DAYS) to CCYYMMDD, with result in GREGORIAN-DATE. Check UDATE-STATUS for possible errors.
Contains %TOJULIAN and %UDATEERR.
This takes a date in the format CCYYMMDD and returns the corresponding week number in the format YYWW. According to international standards each week starts on a Monday, and week 1 of any year is the first week that contains a Thursday. These are the default values that have been defined in UDATE-DAY1-OF-WEEK and UDATE-WEEK1-CONTAINS, but these may be changed if required, using the value 0=SUN, 1=MON, 2=TUE, etc.
This takes a date in the format CCYYMMDD and sets GREGORIAN-DATE to the corresponding week-ending date. Uses UDATE-DAY1-OF-WEEK to show the first day of the week (default = 1 for Monday).
The UNUMBER routines are used to convert a number in display format to a computational value so that it can be used within a program. The input value must have been validated and SET via a VPLUS screen. The output value must be large enough to contain the input value, and must be defined with the correct number of decimal places.
The BNUMBER routines are used to convert values which have not been input via a VPLUS screen, and therefore require a parameter to indicate the number of decimal places that the number should contain, and a status area to indicate invalid input.
Converts the input value to 1 word binary.
Converts the input value to 2 words binary.
Converts the input value to 4 words binary.
Converts the input value to 3 words packed decimal.
Converts the input value to 4 words packed decimal.
Converts the input value to 1 word binary.
Converts the input value to 2 words binary.
Converts the input value to 3 words packed decimal.
Converts the input value to 4 words binary.
The %UCENTER, %ULEFT, %URIGHT, %UPSHIFT and %DOWNSHIFT macros require the input string to be moved into UTEXT-INPUT beforehand. The result will be placed in the output area. The length must be in the range 1-80 characters.
Shift the characters into the centre of the string.
Shift the characters to the left of the string.
Shift the characters to the right of the string.
Change all lower case characters to upper case.
Change all upper case characters to lower case.
This will produce a soundex value (format Annn) from an input string of up to 80 characters in length.
The macro and data areas are defined in copy library member USTRING. This is to be used before accessing a KSAM file to determine whether the user's selection criteria contains a trailing asterisk or not. A trailing asterisk signifies that a generic search is required rather than an exact match. The result will be contained in USTRING-STATUS.
These routines allow individual bits within a 2-byte word to be set, unset, or examined. The bits are numbered 0 to 15, from left to right. Only one bit can be processed with each call.
Ensures that the bit in the target word is set to 1 (ie: ON).
Ensures that the bit in the target word is set to 0 (ie: OFF).
Checks to see if the specified bit in the target word is either ON or OFF. The result is returned in BIT-RESULT.
Passes a string to the COMMAND intrinsic. The result will be returned in CMND-ERROR (0=OK, <0=WARNING, >0=ERROR).
If the COMMAND-CIERROR condition is set this will abort the program.
This will cause the program to abort. A non-zero value should be placed in MENU-SYSTEM-ERROR, and an error message should be placed in VIEW-WINDOW.
If an error occurs while using the MPE intrinsics to access a file this macro will call the UERROR routine to abort the program , with the diagnostic print containing the relevant error number and message.
See also %MPEFILESTATUS.
This will cause the program to pause for the specified number of seconds.
This will convert a time from HHMMSS to HH:MM:SS.
This will set the jcw (job control word) with the specified name to the specified value. The jcw name can be up to 72 characters. The jcw value must be in the range 0-9999.
This will return the value associated with the specified jcw. The result is returned in JCW-VALUE. If the jcw name does not currently exist the value is set to zero.
This will return the byte address for the specified data item.
This will return the word address for the specified data item.
This will open the message catalog with the specified name. It should be included in the USEROPEN routine.
This will retrieve a message from the message catalog. It is used within the UVPLUS routines to retrieve text for window messages and function key labels.
This will close the message catalog. It should be included in the USERCLOSE routine.
This will define the name of the application help catalog. It will not actually be opened until the HELP key is pressed, and will be closed when the user leaves the help subsystem.
This will decode the status value where an error occurs with a file that has the "FILE STATUS IS <dataname>" clause included in the SELECT statement. If the filename is a literal (ie: not a dataname) it must be included in quotes.
Subprograms running under the MENUSON process cannot access the MENU database directly as it is opened only by the parent MENU process. The following macros will communicate with the parent MENU process which will access the database and return the results.
Reads the M-TRAN dataset of the MENU database. Requires copy library member MENUMC IN STANDARD to be defined in working storage.
Reads the M-USER dataset of the MENU database. Requires copy library member MENUMD IN STANDARD to be defined in working storage.
Reads the M-PRINTER dataset of the MENU database. Requires copy library member MENUME IN STANDARD to be defined in working storage.
This will transfer the specified jobstream from the command file on the MENU database to file $OLDPASS. Requires copy library member USTREAM IN STANDARD to be defined in working storage. If an error is found VIEW-NUMERRS will be set, and an error message will be placed in VIEW-WINDOW.
This follows the %USTREAMFIND macro. It validates the printer name and the parameter values entered by the user. If PRINTER-STATUS <> 0 then the printer name is invalid. If PARAM-STATUS <> 0 then the corresponding value supplied by the user is invalid. VIEW-WINDOW will contain the relevant error message.
This follows the %USTREAMVALIDATE macro. It will insert the user's parameter values into the jobstream and stream it. If an error is found USTREAM-CIERR will be set, and the relevant message will be placed in VIEW-WINDOW.
Message files (or Inter Process Communication files) provide a mechanism for one process, or even several processes, to communicate with another.
Defines all the data items required to access the MSG file. The file must be opened and closed within the same module as the file name and number are not passed around in USER-LINKAGE. The record layout must be appended to this area.
Same as %MSGFILEDEFINE, but without the file name and number. These must be defined in USER-LINKAGE, which makes the file accessible to other modules.
Calls the UERROR routine in the event of an error.
Opens the file for read access (single reader only). Sets the record length in <name>-RECLEN, and calls %MSGFILECOUNTERS.
Sets the following values for the specified MSG file:
| <name>-RECORD-COUNT | the number of records in the file |
| <name>-RECORD-LIMIT | the file limit |
| <name>-WRITER-COUNT | the number of current writers to the file |
| <name>-READER-COUNT | the number of current readers of the file |
Calls the FCONTROL intrinsic to set an option either ON or OFF. For example:
| Option 45, value 1 | do not return an END-OF-FILE condition even if the file is empty and there are no more write accessors (ie: continue waiting for input). |
| Option 45, value 0 | allows an END-OF-FILE condition to be returned after the last record has been read and there are no more write accessors. |
| Option 47, value 1 | set the next read to be non-destructive. |
| Option 47, value 0 | set the next read to be destructive. |
Opens the file for write access (multiple writers). Sets the record length in <name>-RECLEN, and calls %MSGFILECOUNTERS.
Same as %MSGFILEOPENW, but does not abort if the FOPEN fails. This allows the program to deal with the error without aborting.
Writes a record to the MSG file, then calls FCONTROL option 6 to flush the buffer to ensure that no data is lost (by default the file system will wait until the buffer is full before it writes to disc, and if a system crash occurs the current buffer is lost).
Reads the first available record from the file, and destroys it unless the non-destructive read has been set. All subsequent reads will retrieve the same record until the destructive read is set on. The END-OF-FILE condition is not returned until the file is empty and there are no more write accessors, but an FCONTROL option can be set to wait even though there are no more writers.
Closes the MSG file.
- END -