Micro Focus Enterprise Developer 2.3 Update 2 for Eclipse > Programming > Mainframe Programming > AppMaster Builder > Reference > Customizer/Micro Focus Generator (MFG) > MFG Structures

MFG Structures

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following Micro Focus Generator (MFG) structures can be used to create Customizer rules in AMB programs.

Note: Pay attention to the "Syntax" section for each structure. When a structure has no arguments, do not code %structure ().

% * (comments)
Document MFG code with comments.
% BEGIN
Use in conditional or looping statement blocks to control the number of columns that AMB or APS moves the blocks during processing. The number of columns that you indent % BEGIN in a conditional or looping construct is the same number of columns that AMB moves the subordinate block to the left. Default processing moves the block to the starting column of the controlling conditional or looping construct.
% DECLARE
Define a % DECLARE table made of variable assignments that can be referenced either directly (after assigning values to its subscripts), or by searching with the % LOOKUP structure.
% DEFINE
Specify the rule name and formal arguments in a USERMACS file, or AMB program.
% ESCAPE
Stop processing the rule and continue processing at the line immediately following the rule call.
% IF/ELSE-IF/ELSE
Evaluate a condition.
% INCLUDE
Open, read, and process a user-defined rule, copybook, or other file in a AMB program.
% LOOKUP
Reference a % DECLARE table.
% REPEAT
Establish a loop and test a condition.
% SET BLANK or NOBLANK
Print all blank lines that appear in the input, or suppress blank lines from printing.
% SET COMMUNICATION
Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the Communication Section.
% SET DATA
Move all source code appearing between this statement and the next % SET statement from the Procedure Division to immediately after the Data Division header.
% SET EPILOGUE
Call a rule after all other Customizer processing finishes. Although you can specify only one rule call per EPILOGUE statement, you can write multiple statements.
% SET ERROR FATAL WARNING INFO
Send a message to the final message report of the compile, as follows.
% SET FILE
Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the File Section. AMB generates the File Section header, unless it is in the input source or if the rule is an EPILOGUE rule.
% SET FILE-CONTROL
Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the File-Control paragraph. AMB generates the Input-Output Section and File-Control headers, unless they are in the input source or if the rule is an EPILOGUE rule.
% SET LAST-STATUS
Reset the value of the &APS-LAST-STATUS built-in function to 0. Use this rule to monitor the success or failure of one or more statements. The global status remains unchanged.
% SET LINKAGE
Move all source code appearing between this statement and the next % SET statement to the end of the Linkage Section. AMB generates the Linkage Section header, unless it is in the input source or if the rule is invoked by % SET EPILOGUE. Use % SET LINKAGE in the Procedure Division.
% SET LOCATION structure
Establish a location in a single output file where the MFG should place subsequent output lines. %SET-LOCATION can establish a new section in an output file, as well as reposition subsequent output lines at the end of a previously established section.
% SET LOOP-LIMIT
Override the loop counter default (500) in the AMB CNTL file APSDBDC. The internal default set by the MFG is 999999. % SET LOOP-LIMIT is often used to locate the cause of infinite loops.
% SET NORMAL-OUTPUT
Restore the output file to the file designated by /POSTSOUT= or the /DD for POSTSOUT.
% SET OUTPUT-FILE
Establish a new output file to receive MFG output, or redirect MFG output to a previously established output file.
% SET PROCEDURE
Mark the end of the preceding % SET statement that moves source to other locations in the program, such as % SET WORKING-STORAGE and % SET DATA DIVISION, and return to the location of the statement, not to the beginning or end of the Procedure Division.
% SET RETAIN-LINE-SUFFIX
Specify that generator statements use their own source line suffixes (beyond the right margin) on output, instead of the inherited value from a higher level, for the current and lower execution levels. An indentation level is changed by either a % INCLUDEstatement or a rule invocation.
% SET RETAIN-LINE-SUFFIX-LEVELS
Specify the number of levels of execution, including the current level and below, that use their own source line suffixes (beyond the right margin) on output, instead of the inherited value from a higher level. This identifies the source lines, enabling AMB to refer to errors.
% SET SECTION
Establish an area in the output file where the MFG can append output lines. % SET SECTION acts similar to % SET LOCATION by establishing a new section in the current output file for output lines. However, % SET SECTION does not receive output in the section named in the statement.
% SET SPECIAL-NAMES
Use in the Procedure Division to move all source code appearing between this statement and the next % SET statement to the end of the Special-Names paragraph. AMB generates the Special-Names header unless it is in the input source or if the rule is an EPILOGUE.
% SET TRACE
Trace the generation execution of selected segments of rule source code, and produce a detailed execution log. You can turn tracing features on and off in different sections of rule logic. This ability to selectively debug reduces the volume of debug output. % SET TRACE traces all variables; you can use % SET WATCH to trace individual variables.
% SET TRACEBACK
Limit the rule call trace function.
% SET WATCH
Trace selected variables. Whereas % SET WATCH traces individual variables, % SET TRACE traces all variables.
% SET WORKING-STORAGE
Use in the Procedure Division to move source code appearing between this statement and the next % SET statement to the end of the Working-Storage Section, immediately above the % SET END-WORKING-STORAGE statement, if coded.
% SET WRITE-CONTROL
Equivalent to % SET TRACE, except that the INFO and NOINFO options are invalid. Output is written to the log, not to the generated output (POSTSOUT).
% UNTIL/WHILE
Establish a loop and test a condition to execute a subordinate statement block either until or while a single or compound condition is satisfied.
&columnnumber+source
Specify the output column number at which to place the associated statement source code.
&variable+suffix
Append a literal suffix to a variable data name. You precede the suffix with a plus symbol (+). During processing, the plus symbol disappears--it is not replaced with a space--and the suffix appends onto the resolved variable value.
&ABS
Holds the absolute value of a numeric argument. Character strings are acceptable as arguments if they can be converted to numeric type.
&APS-BLANK-STATUS
Determine whether the generator ignores blank lines or passes them through to the output.
&APS-ELAPSED-SECONDS
Holds the number of seconds elapsed since the start of the job. &APS-TASK-MILLISECONDS returns the number of milliseconds elapsed since the start of a job. Use these rules to examine sections of source code for performance improvement.
&APS-EPILOGUE
Holds the rule name that the last % SET EPILOGUE put into the EPILOGUE queue.
&APS-FULL
Holds a PIC string containing a 4-byte mainframe full-word or PC double word binary picture specification.
&APS-HALF
Holds a binary PIC string containing a 2-byte mainframe half-word or PC word binary picture specification.
&APS-INDENT
Holds the indentation level of the current rule. It returns the column position of the $ of the invoking rule; otherwise, it returns the column position of the left margin (usually column 7 when LANG=COBOL).
&APS-LAST-STATUS
Holds the generation status since the last % SET LAST-STATUS statement executed. Use this rule to determine the success or failure of a statement sequence. For the global status of the generator process, use &APS-STATUS.
&APS-LOOP-LIMIT
Holds the current value of the internal loop counter, LOOP-LIMIT.
&APS-MCS
Holds the screen or window generation name from the MFG control file that is passed to the MFG.
&APS-MDB
Holds the Multiple Database (MDB) generation target you specified.
&APS-MDC
Holds the Multiple Data Communications (MDC) target, which is the data communication generation target value specified in your application.
&APS-OUTPUT-FILE
Contains the name of the output file where the output lines are. Use % SET OUTPUT-FILE to name the output file receiving output lines.
&APS-OUTPUT-LOCATION
Contains the name of the output file where the output lines are. Use % SET OUTPUT-FILE to name the output file receiving output lines.
&APS-PROGRAM-ID
Holds the PROGRAM-ID name from the Identification Division.
&APS-PSB-NAME
Holds the data view--PSB or subschema--specified for your program.
&APS-STATUS
Holds the global status of the generator process. This value is identical to the return code that the generator returns. The value increases monotonically throughout processing as the generator encounters progressively more serious errors.
&APS-TASK-MILLISECONDS
Holds the number of milliseconds the generator used since the job start. Use this rule to examine sections of source code for performance improvement. To return the number of seconds elapsed, use &APS-ELAPSED-SECONDS.
&AS-HEX
Holds the contents of a variable--a hexadecimal character text string that represents the input argument. This rule accepts both numeric and text type arguments.
&CAT
Equivalent to &STRING.
&COMPILETIME
Holds the compile date and time in dd mmm yy hh.mm.ss format.
&CONCAT
Equivalent to &STRING.
&DEFINED
Determines if a specific rule or variable has a defined value and returns a true value (1) if defined, and a false value (0) if not defined.
&DEFVAL
Holds the string or number value of the last &DEFINED variable in &variablename.
&ENCODING
Determines whether the argument contains single-byte or double-byte characters and returns either SBCS or DBCS. &ENCODING tests each byte to determine whether the byte is within a numeric range; the range is determined by your country code. The generator returns SBCS for country codes--such as US--that do not include double byte characters.
&ENTRY
Create a new built-in function by establishing a symbolic name and associating it with an entry point in a DLL. This is used with the MFG API that allows the MFG to call functions with a predefined signature that reside in a DLL.
&HEX-AS-NUMBER
Convert a text string containing hexadecimal characters to an unsigned numeric value.
&HEX-AS-SIGNED
Convert a text string containing hexadecimal characters to a signed 1-, 2-, or 4-byte value.
&HEX-AS-STRING
Return a string containing the characters represented by the hex character sequence, thus eliminating unprintable characters in the source code.
&HEX-AS-UNSIGNED
Equivalent to &HEX-AS-NUMBER.
&IG-DEBUG-TYPE
Returns a string indicating whether the generator was built as an internal debug or production version. For example, if you run IG version 1.0 GA production build, then &IG-DEBUG-TYPE returns the string "PRODUCTION".
&IG-MAJOR-VER
Holds a string indicating the major version number of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
&IG-MINOR-VER
Holds a string indicating the minor version number of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
&IG-RELEASE
Holds a string indicating the release level of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
&IG-TYPE
Contains the environment the generator was built for. This function provides data to document a run, such as a comment in the generated output.
&IG-VER
Contains the entire version and release level of the generator. This function provides data to document a run, such as a comment in the generated output.
&INDEX
Search a string, from left to right, for the first occurrence of a character-string. Then, return a number identifying the character position.
&IS-ALPHA
Examines an argument and returns 1 if the argument contains alphabetic characters only; otherwise returns 0.
&IS-ALPHANUMERIC
Examines an argument and returns 1 if the argument contains alphabetic and numeric characters only: A-Z, a-z or 0-9; otherwise, returns 0.
&IS-DECIMAL
Determines whether the variable contains the following valid numeric characters, and if so, returns 1; otherwise, returns 0.
&IS-DIGITS
Examines an argument and returns 1 if the argument contains valid numeric digits only: 0123456789; otherwise, returns 0.
&IS-HEX
Examines an argument and returns 1 if the argument contains valid hexadecimal characters: 0-9, A-F, or a-f; otherwise, returns 0.
&IS-LOWER
Examines an argument and returns 1 if the variable value contains lower case characters only; otherwise, returns 0.
&IS-NUMERIC
Examines an argument and returns 1 if the argument contains valid numeric characters, as follows; otherwise, returns 0.
&IS-PRINTABLE
Examines an argument and returns 1 if the argument contains printable characters only: characters with hexadecimal representation 20 hex through 7E hex. Otherwise, it returns 0.
&IS-UPPER
Examines an argument and returns 1 if the variable value contains upper case characters only; otherwise, returns 0.
&LENGTH
Examines an argument string and returns a number specifying its length.
&LOW-CASE
Equivalent to &LOWER.
&LOWER
Returns a copy of a string with all upper case characters converted to lower case. Other characters remain unchanged.
&MAX
Finds and holds the highest number in a set of signed numeric arguments.
&MIN
Finds and holds the lowest signed value in a set of signed numeric arguments.
&MOD
Determines whether a number is divisible by another by returning the numeric remainder from dividing the first argument by the second.
&NUM
Construct a numeric typed value from the concatenation of the arguments. Use this function, instead of evaluation brackets, to increase the level of semantic expression in the program, that is, indicate that a string is being constructed.
&NUMERIC
Determines whether a variable is represented internally in numeric form and returns 1 if numeric or 0 if non-numeric.
&OPSYS-MAJOR|MINOR-VER
These functions contain the major and minor version numbers of the operating system executing the MFG.
&OPSYS-TYPE
Contains the name of the executing operating system, e.g., "NT". Use this function to include a different rule file depending on where the MFG is generating.
&PARSE
Parses a Customizer text string. &PARSE facilitates the following tasks.
&RANDOM
Holds a pseudo-random number in the range.
&SEED
Provides an initial value for the &RANDOM function. This function provides statistical control (reproducibility) over programs using &RANDOM.
&STRING
Concatenates text strings, variable values, or expressions, and returns the result. Use &STRING instead of evaluation brackets to increase the level of semantic expression in the program, in the sense of indicating a string is being constructed.
&STRLWR
Equivalent to &LOWER.
&STRUPR
Equivalent to &UPPER.
&SUBST
Holds the original string with only the first occurrence of the match string replaced by the substitute string. If the match string does not occur in the original string, &SUBST returns a copy of the original string. The original arguments remain unchanged.
&SUBST-ALL
Holds the original string along with all occurrences of the match string replaced by the substitute string. If the match string does not occur in the original string, &SUBST returns a copy of the original string. The original arguments remain unchanged.
&SUBSTR
Extract a substring from a string, starting with startcolumn and continuing for length .
&TO-LOWER
Equivalent to &LOWER.
&TO-UPPER
Equivalent to &UPPER.
&UP-CASE
Equivalent to &UPPER.
&UPPER
Return a copy of the original string with all lower case characters in the variable converted to upper case. Other characters remain unchanged. Use &IS-UPPER or &IS-LOWER to test if the string is upper or lower case.

Parent topic: Customizer/Micro Focus Generator (MFG)