THE MATERIAL USED IN THIS SPECIFICATION, INCLUDING BUT NOT LIMITED TO CONSTRUCTION TIMES AND OPERATING SPEEDS, IS FOR INFORMATIONAL PURPOSES ONLY. ALL SUCH MATERIAL IS SUBJECT TO CHANGE WITHOUT NOTICE. CONSEQUENTLY DEC MAKES NO CLAIM AND SHALL NOT BE LIABLE FOR ITS ACCURACY. THIS DOCUMENT DESCRIBES THE OPERATIONAL PROCEDURES FOR MACY11, AN ASSEMBLER WHICH OPERATES ON THE PDP-10, TRANSLATING MACRO-11 SOURCE LANGUAGE INTO BINARY FILES ACCEPTABLE TO LINK-11. MACY11 TABLE OF CONTENTS CHAPTER 1 INTRODUCTION CHAPTER 2 OPERATING PROCEDURES CHAPTER 3 LISTING CONTROL CHAPTER 4 ENABLE/DISABLE CONTROL CHAPTER 5 DISCREPANCIES BETWEEN MACY11 AND ...... CHAPTER 6 USER-DEFINED SWITCH DEFAULTS CHAPTER 1 INTRODUCTION MACY11 IS AN ASSEMBLER WHICH OPERATES ON THE PDP-10 AND ASSEMBLES CODE FOR THE PDP-11. WITH THE EXCEPTION OF THE VARIATIONS LISTED IN THIS MANUAL, VERSION 27 IS EQUIVALENT TO THE MACRO-ASSEMBLER OF PDP-11 RSX-11D. PLEASE NOTE THAT VERSION 27 COMPLETELY REPLACES VERSIONS 624 AND 26B. THE DIFFERENCES BETWEEN VERSION 27 OF MACY11 AND VERSION 624 ARE DESCRIBED IN A FILE OBTAINABLE BY TYPING: .PRINT SYS:MACY11.DOC . CHAPTER 2 OPERATING PROCEDURES WHILE MACY11 IS DESIGNED TO BE LANGUAGE COMPATIBLE WITH THE MACRO-11 LANGUAGE, ITS PDP-10 OPERATING ENVIRONMENT NECESSITATES A PDP-10 STYLE OPERATING PROCEDURE. THE ASSEMBLER MAKES TWO PASSES OVER THE SOURCE, OUTPUTTING THE BINARY AND LISTING FILES DURING PASS TWO AND APPENDING A SYMBOL OR CROSS REFERENCE TABLE TO THE LISTING FILE. PDP-10 MEMORY IS DYNAMICALLY ALLOCATED FOR LARGE SYMBOL TABLE STORAGE AND MACRO STORAGE. 2.1 LOADING MACY11 VERSION 27 OF MACY11 IS CALLED BY TYPING: R MACY11 AS A MONITOR COMMAND. SHOULD ANY PROBLEMS ARISE WITH VERSION 27, THE PREVIOUS VERSION (WHICH IS 624) CAN BE OBTAINED BY TYPING: RU OLD:MACY11 2.2 INITIAL DIALOGUE WHEN THE ASSEMBLER IS READY TO ACCEPT THE USER'S COMMAND STRING, IT TYPES AN ASTERISK. THE USER MUST NOW TYPE HIS COMMAND STRING ON THE SAME LINE. THE GENERAL FORM OF THE COMMAND STRING IS: BINARY OUTPUT, LISTING OUTPUT _ SOURCE INPUT(S) EACH INPUT/OUTPUT SPECIFICATION CONSISTS OF THE GROUP: DEV:FILNAM.EXT[PROJ.,PROG.]/SWITCH:ARG 1. DEV IS: DSK FOR DISK PTP FOR HIGH SPEED PUNCH DTAN FOR DECTAPE N MTAN FOR MAG TAPE N TTY FOR THE USER'S TELETYPE IF NOT SPECIFIED, THE DEVICE IS ASSUMED TO BE THE DISK. 2. FILNAM IS THE FILE NAME OF THE APPROPRIATE FILE. 3. EXT IS THE FILE NAME EXTENSION FOR THAT FILE. IF IS NOT SPECIFIED, THE ASSUMPTIONS ARE: BINARY STRING: .OBJ (RELOCATABLE) OR .BIN (ABSOLUTE) LISTING STRING: .LST SOURCE STRING: .P11,.PAL,. ,.MAC OR .M11 (IN THAT ORDER) 4. [PROJ.,PROG.] IS THE PROJECT-PROGRAMMER NUMBER ASSIGNED FOR THE DISK AREA TO BE USED. IF NOT SPECIFIED, THE USER'S LOCAL AREA IS ASSUMED. ONCE SPECIFIED, THE NUMBER PAIR BECOMES THE NEW DEFAULT ASSUMPTION FOR THE FOLLOWING FILES. 5. SWITCHES ARE SPECIFIED BY PRECEDING EACH WITH A SLASH CHARACTER. SWITCH ARGUMENTS ARE PRECEDED BY COLONS. /LI SIMULATE .LIST DIRECTIVE (SEE CHAPTER 3). /NL SIMULATE .NLIST DIRECTIVE (SEE CHAPTER 3). /EN SIMULATE .ENABL DIRECTIVE (SEE CHAPTER 4). /DS SIMULATE .DSABL DIRECTIVE (SEE CHAPTER 4). /CRF APPEND CROSS REFERENCE TABLE TO THE LISTING FILES (SEE CHAPTER 3). /N SUPPRESS ERROR MESSAGES AND EXPANDED SUMMARY TO THE TELETYPE. /I OUTPUT BINARY IN IMAGE MODE (ONE BYTE PER 36 BIT PDP-10 WORD). THIS SWITCH MUST BE USED TO PIP DIRECTLY TO PAPER TAPE. /P PACK BINARY OUTPUT. THIS IS THE DEFAULT CASE AND THE SWITCH IS NOT NEEDED. /CDR SIMULATE CARD READER INPUT. THIS IS ACTUALLY INDEPENDENT OF THE PHYSICAL INPUT DEVICE BUT CAUSES THE ASSEMBLER TO IGNORE ALL CHARACTERS ON A LINE AFTER THE 72ND. /SOL SEQUENCE OUTPUT LINES (SEE CHAPTER 3). /GNS GENERATE NEW SOURCE (SEE CHAPTER 3). /NSQ SUPPRESS LISTING OF PDP-10 STYLE SEQUENCE NUMBERS. /EQ EQUATE THE FOLLOWING SYMBOLS TO ZERO. THIS IS A METHOD FOR INTRODUCING CONDITIONAL ARGUMENTS WITHOUT CREATING SPECIAL PARAMETER TAPES. "/EQ:SYM1:SYM2" IS THE EQUIVALENT OF THE SOURCE STATEMENTS "SYM1=0" AND "SYM2=0". CHAPTER 3 LISTING CONTROL THE MACRO-11 LANGUAGE SPECIFIES, FUNCTIONALLY, A SET OF LISTING CONTROLS. ALL IMPLEMENTATIONS OF THE MACRO-11 LANGUAGE WILL ACCEPT SOURCE STATEMENTS CONTAINING THESE CONTROLS BUT SPECIFIC ACTION TAKEN MAY VARY WITH THE IMPLEMENTATION. THIS ENABLES THE ASSEMBLERS TO HAVE A DEGREE OF FREEDOM WHILE KEEPING THE SOURCE LANGUAGE COMPATIBLE. FOR EXAMPLE, A MINI-VERSION MIGHT NOT EVEN HAVE SELECTIVE LISTING CONTROL, BUT IT WOULD NOT FLAG AN ERROR WHEN LEGITIMATE REQUESTS WERE MADE. MACY11 HAS TWO CATEGORIES OF LISTING CONTROLS: MACRO-11 COMPATIBLE, WHICH MAY BE SPECIFIED EITHER IN SOURCE STATEMENTS OR IN THE COMMAND STRING, AND A SUPERSET WHICH IS LIMITED TO THE COMMAND STRING. 3.1 SOURCE STATEMENT LISTING CONTROL LISTINGS ARE CONTROLLED AT SOURCE STATEMENT LEVEL THROUGH THE USE OF THE .LIST AND .NLIST DIRECTIVES. THESE ARE COMPLEMENTARY IN THAT ANY FUNCTION WHICH CAN BE ENABLED BY A .LIST CAN BE DISABLED BY A .NLIST. TO REDUCE REDUNDANCY, THE FOLLOWING DESCRIPTIONS WILL EMPHASIZE THE .LIST WHILE IMPLYING THE .NLIST COMPLEMENT. THE FOLLOWING ARE THE ALLOWABLE ARGUMENTS FOR THE .LIST DIRECTIVE ALONG WITH THE DEFAULT SETTINGS (LI FOR .LIST AND NL FOR .NLIST): THE FIRST GROUP CONTROLS INTRA-LINE LISTING. SUPPRESSION OF ANY OF THESE WILL CAUSE THE ASSEMBLER TO UTILIZE THE SPACE BY MOVING THE REMAINDER OF THE LINE OVER. SEQ-LI LIST THE SEQUENCE NUMBERS. THESE NUMBERS REPRESENT THE SOURCE LINE NUMBERS AND ARE REPLACED BY THE NESTING LEVEL IN PARENTHESES FOR GENERATED LINES (MACROS, ETC.). LOC-LI LIST THE VALUE OF THE LOCATION COUNTER. BIN-LI LIST THE BINARY CODE GENERATED BY THE ASSEMBLER. SRC-LI LIST THE SOURCE STATEMENT. THIS IS INCLUDED PRIMARILY FOR COMPLETENESS. COM-LI LIST THE COMMENT FIELD. BEX-LI LIST BINARY CODE WHICH REQUIRES MORE THAN ONE LISTING LINE. SUPPRESSION OF THIS IS PARTICULARLY USEFUL IN REDUCING THE LENGTH OF LISTING REQUIRED FOR LONG .ASCII STRINGS. THE FOLLOWING ARGUMENTS PERTAIN TO ENTIRE STATEMENTS: MD -LI LIST MACRO DEFINITIONS. MC -LI LIST MACRO CALLS. ME -NL LIST MACRO EXPANSIONS. THE DEFAULT CAUSES THE EXPANSION TO BE SUPPRESSED IN THE INTEREST OF SUPPLY ECONOMY. ME CONTROLS ALL GENERATED TEXT (.MACRO'S, .REPT'S, AND .IRP'S). CAUTION - DUE TO THEIR DUAL NATURE, .REPT'S AND .IRP'S QUALIFY BOTH AS DEFINITIONS AND CALLS. MACY11 TREATS MD AND MC AS A PAIR IN THESE CASES, SUPPRESSING THE LISTING IF EITHER IS SET. CND-LI LIST CONDITIONALS. SUPPRESSION CAUSES UNSATISFIED CONDITIONALS AND ALL CONDITIONAL DIRECTIVES (WHETHER SATISFIED OR NOT) TO BE NOT LISTED. SYM-LI APPEND A SYMBOL TABLE TO THE LISTING FILE. TTM-** LIST IN TELETYPE FORMAT (ONE COLUMN OF BINARY TO A LINE, TRUNCATION AFTER 72 COLUMNS). DEFAULT SETTING IS DETERMINED BY THE OUTPUT DEVICE SPECIFIED: ENABLED IF THE PHYSICAL DEVICE IS TTY AND DISABLED (LINE PRINTER MODE) IN ALL OTHER CASES. TOC-NL LIST A TABLE OF CONTENTS DURING PASS ONE. THIS CONSISTS OF THE .SBTTL DIRECTIVES BEING LISTED AT THE BEGINNING OF THE LISTING FILE. EACH LINE CONSISTS OF THE LINE NUMBER AND ALL TEXT TO THE RIGHT OF THE .SBTTL DIRECTIVE. LD -NL LIST LISTING DIRECTIVES. SPECIFICALLY, THIS CAUSES ALL .LIST/.NLIST DIRECTIVES WHICH HAVE NO ARGUMENTS TO BE LISTED. ITS PRIMARY USE IS IN DEBUGGING LISTING CONTROL. .LIST AND .NLIST DIRECTIVES WITH NO ARGUMENTS PERFORM AN OVER- RIDE FUNCTION. THEY CONTROL A LISTING "LEVEL" WHICH IS DECREMENTED FOR EACH .NLIST AND INCREMENTED FOR EACH .LIST. THE LEVEL COUNT IS USED AS A THREE WAY SWITCH: 1. ZERO (INITIAL CONDITION): NO SPECIAL ACTION. 2. LESS THAN ZERO: UNCONDITIONALLY SUPPRESS THE LISTING EXCEPT FOR LINES CONTAINING ERRORS. 3. GREATER THAN ZERO: LIST UNCONDITIONALLY. .LIST/.NLIST ARE NORMALLY PAIRED TO RETURN THE LEVEL COUNT TO ZERO. THE .NLIST/.LIST SEQUENCE IS USED TO SUPPRESS A RANGE WHICH IS NORMALLY LISTED, WHILE THE .LIST/.NLIST SEQUENCE IS USED TO OVER-RIDE A RANGE WHICH IS NORMALLY SUPPRESSED, SUCH AS IN A MACRO EXPANSION. THE LEVEL COUNT ALLOWS MACRO EXPANSIONS TO USE THE LISTING CONTROL AND RETURN IT TO ITS PREVIOUS STATE. 3.2 COMMAND STRING EQUIVALENTS THE COMMAND STRING CONTAINS THE EQUIVALENT OF ALL THE ABOVE .LIST AND .NLIST FUNCTIONS AS WELL AS SOME THAT ARE NOT AVAILABLE AT SOURCE LEVEL (AND NOT NECESSARILY AVAILABLE IN OTHER VERSIONS OF MARCO-11). INDEED, MANY OF THE SOURCE LEVEL ARGUMENTS ARE OF PRIMARY INTEREST AT COMMAND STRING LEVEL BUT CAN BE USED IN THE SOURCE TO MODIFY DEFAULT SETTINGS. THE COMMAND STRING EQUIVALENTS OF .LIST AND .NLIST ARE /LI AND /NL, RESPECTIVELY. ARGUMENTS ARE SPECIFIED BY PRECEDING THEM WITH COLONS. THUS /NL:BEX:CND IS THE EQUIVALENT OF .NLIST CND,BEX. IN ALL CASES, COMMAND STRING SWITCHES OVERRIDE THEIR SOURCE LEVEL EQUIVALENTS (AS WELL AS PREVIOUS OCCURRENCES IN THE COMMAND STRING). EFFECTIVELY, SPECIFICATION OF A FUNCTION IN A COMMAND STRING WILL CAUSE ALL ITS SOURCE LEVEL EQUIVALENTS (AND THEIR COMPLEMENTS) TO BE IGNORED. I.E. /LI:ME WOULD ENABLE THE LISTING OF MACRO EXPANSIONS AND CAUSE ALL ".LIST/.NLIST ME" DIRECTIVES TO BE IGNORED. /LI (NO ARGUMENTS) CAUSES EVERYTHING TO BE LISTED, WHILE /NL SUPPRESSES THE LISTING OF ALL BUT ERROR LINES, THE SYMBOL TABLE, AND THE CROSS REFERENCE TABLES. 3.3 OTHER LISTING CONTROLS THE FOLLOWING SWITCHES ARE, IN GENERAL, UNIQUE TO MACY11. THEY ARE SPECIFIED IN THE OUTPUT SIDE OF THE COMMAND STRING BY PRECEDING THE MNEMONIC BY A SLASH: /N SUPPRESS ERROR MESSAGES TO THE TELETYPE (UNLESS IT IS ALSO THE LISTING DEVICE). /CRF APPEND A CROSS REFERENCE TABLE TO THE LISTING FILE. MACY11 ACCOMPLISHES THIS IN THE FOLLOWING MANNER: 1. THE LISTING FILE IS GENERATED IN THE NORMAL WAY DURING PASS TWO, USING THE NAME SPECIFIED BY THE USER. 2. SIMULTANEOUSLY, A TEMPORARY FILE (XXXCRF.TMP, WHERE XXX IS THE JOB NUMBER) IS CREATED. THIS CONTAINS ENCODED CREF INFORMATION. 3. AT THE END OF PASS TWO, THE TEMPORARY FILE IS READ AND THE CREF INFORMATION IS INTEGRATED INTO THE SYMBOL TABLE. 4. THE REFERENCES ARE APPENDED TO THE LISTING FILE. IF INSUFFICIENT CORE WAS AVAILABLE TO BUILD THE TABLE, THE PROCESS IS REPEATED. WHEN THROUGH, THE TEMPORARY FILE IS DELETED. THE CROSS REFERENCE TABLE FORMAT IS AS FOLLOWS: 1. THE SYMBOL ITSELF. 2. ITS SYMBOL TABLE VALUE, UNLESS .NLIST SYM WAS SPECIFIED. THERFOR THE SYMBOL TABLE ITSELF IS ALWAYS PRE-EMPTED. 3. ALL REFERENCES TO THE SYMBOL, EXCEPT THAT NO MORE THAN ONE REFERENCE TO A GIVEN SOURCE LINE WILL BE LISTED. SYMBOLS IN GENERATED TEXT ALWAYS REFER TO THE PREVIOUS SOURCE LINE. 4. DEFINING OCCURRENCES ARE FLAGGED WITH A "#". 5. DESTRUCTIVE REFERENCES ARE FLAGGED WITH A "*". THESE ARE DEFINED TO BE ALL SYMBOLS ENCOUNTERED IN OP-CODE FIELDS WHICH STORE INTO A MEMORY LOCATION OR A REGISTER. THUS THE FIRST FIELD OF A JSR, THE SECOND FIELD OF AN ADD, BUT NEITHER OF THE FIELDS IN A CMP INSTRUCTION. 6. AS MANY REFERENCES PER LISTING LINE AS POSSIBLE, DEPENDING UPON THE "TTM" MODE, ARE USED. THIS CAN BE INCREASED BY SUPPRESSING "SYM". /SOL SEQUENCE OUTPUT LINES. LISTINGS ARE NORMALLY SOURCE ORIENTED: 1. SEQUENCE NUMBERS REFLECT THE SOURCE LINE NUMBER. 2. MACRO EXPANSION LINES HAVE THEIR NESTING LEVEL, IN PARENTHESES, IN THE SEQUENCE NUMBER FIELD. 3. LINES CONTAINING NOTHING BUT A FORM FEED ARE NOT LISTED BUT CAUSE THE SEQUENCE NUMBER TO BE INCREMENTED. 4. PAGE NUMBERS REFLECT PHYSICAL INPUT PAGES (INCREMENTED ONLY UPON ENCOUNTERING A FORM FEED). PAGES FORCED BY THE ASSEMBLER HAVE A -N TO REFLECT AN EXTENSION PAGE. I.E. IF THE ASSEMBLER HAD ENCOUNTERED 3 FORM FEEDS AND WAS ON ITS THIRD LISTING PAGE SINCE THE LAST ONE, IT WOULD BE "PAGE 4-2". WHEN /SOL IS SPECIFIED, LISTINGS ARE OUTPUT ORIENTED: 1. LISTED LINES HAVE CONSECUTIVE NUMBERS, EXCEPT FOR BINARY EXTENSIONS. 2. PAGE NUMBERS REFLECT THE NUMBER OF PAGES LISTED. /GNS GENERATE A NEW SOURCE. THIS CAUSES THE LISTING FILE TO TAKE ON THE APPEARANCE OF A SOURCE FILE. SPECIFICALLY, IT: 1. SUPPRESSES THE LISTING OF HEADERS, ERROR FLAGS, SUMMARY BLOCKS, AND ANY OTHER OUTPUT OVER WHICH THE USER OTHERWISE WOULD HAVE NO CONTROL. 2. SIMULATES A /NL:SEQ:LOC:BIN:BEX:ME. THEREFOR, BY ITSELF, IT RECREATES THE SOURCE FILE. NORMAL USAGE WOULD HAVE SUPPLEMENTARY SWITCHES FOLLOWING IT. I.E. /GNS/NL:MD:MC /LI:ME WOULD REPLACE MACROS, REPEATS, AND IRPS BY THEIR GENERATED CODE, /GNS/NL:CND WOULD PURGE CONDITIONALS, AND /GNS/LI:SEQ WOULD BE AN EXPENSIVE WAY OF CREATING A SEQUENCE NUMBERED LISTING OF THE SOURCE FILE. CHAPTER 4 ENABLE/DISABLE CONTROL AS AN ALTERNATIVE TO THE PROLIFERATION OF DIRECTIVES, MACRO-11 USES ONE COMPLEMENTARY PAIR, .ENABL/.DSABL, WITH ARGUMENTS. THEIR COMMAND STRING EQUIVALENTS ARE /EN AND /DS. THE RELATIONSHIP BETWEEN COMMAND STRING AND SOURCE STATEMENT SPECIFICATION, AS WELL AS THEIR ARGUMENT SPECIFICATION, IS THE SAME AS IN LIST/NOLIST. FPT FLOATING POINT TRUNCATION. ".ENABL FPT" IS EQUIVALENT TO ".TRUNC" WHILE ".DSABL FPT" IS EQUIVALENT TO ".ROUND". ABS EQUIVALENT TO "/A" OR ".ABS" IN MACX11. NPP ".ENABL NPP" CAUSES SUPPRESSION OF THE OUTPUT OF THE FOLLOWING CODE, WHILE ".DSABL NPP" CAUSES ITS RESUMPTION. ERF ERROR FLAGS CAN BE SELECTIVELY SUPPRESSED (OR ENABLED) BY SPECIFYING ERF, DIRECTLY FOLLOWED BY THE SELECTED ERROR CHARACTERS. "/DS:ERFZM" WOULD CAUSE "M" AND "Z" ERRORS TO BE IGNORED, "/DS:ERF" WOULD CAUSE ALL ERRORS TO BE IGNORED, AND "/EN:ERFX" WOULD CAUSE "X" FLAGS (JMP'S WHICH COULD HAVE BEEN BR'S) TO BE FLAGGED. CHAPTER 5 DISCREPANCIES BETWEEN MACY11 V27 AND ..... ..... MACRO-11 OF RSX-11D AND DOS V9 THERE ARE TWO SIGNIFICANT DIFFERENCES BETWEEN THESE ASSEMBLERS AND MACY11. ONE DIFFERENCE RELATES TO PSECTS, IN THAT MACRO RSX-11D WILL DEFAULT OCCURRENCES OF .ASECT AND .CSECT PSEUDO-OPS TO TO .PSECT IN THE OBJECT OUTPUT. MACY11 V27 WILL NOT GENERATE PSECTS UNLESS EXPLICITLY TOLD TO DO SO (BY USE OF THE .PSECT PSEUDO-OP). ANOTHER DIFFERENCE IS THAT RSX-11D WILL ACCEPT LOCAL SYMBOLS OF THE FORM N$, WHERE N IS AN INTEGER AND 1<=N<=65535. THE SAME IS TRUE OF MACY11 EXCEPT THAT THE UPPER BOUND ON N IS 127, RATHER THAN 65535. ..... MACRO-11 OF DOS V8 AND EARLIER VERSIONS OF MACY11 ALL OBJECT OUTPUT FROM MACY11 V27 IS AS IT WAS BEFORE. THE USER- LEVEL DIFFERENCES ARE THAT MACY11 V27 DEFAULTS ALL UNDEFINED SYMBOLS TO GLOBALS, AND THAT RSX-STYLE DEFAULT REGISTER DEFINITIONS ARE AUTOMATICALLY IN EFFECT. IF THESE FEATURES ARE NOT DESIRED, THEY CAN BE DISABLED IN EITHER OF TWO WAYS: 1. THE STATEMENTS .DSABL REG .DSABL GBL CAN BE INCLUDED IN THE SOURCE, OR 2. THE SWITCH /DS:REG:GBL CAN BE PLACED IN THE COMMAND STRING TO MACY11. ALSO, PLEASE NOTE THAT DEFAULT GLOBALIZATION IS AUTOMATICALLY DISABLED FOR ABSOLUTE ASSEMBLIES (I.E., FOR THOSE SOURCE FILES WHICH CONTAIN .ENABL ABS STATEMENTS, OR THE COMMAND STRINGS FOR WHICH CONTAIN THE SWITCH /EN:ABS ). CHAPTER 6 USER-DEFINED SWITCH DEFAULTS MACY11 is capable (as of v27(655)) of accepting user-defined switch defaults. Any switches that are valid in a command string may be specified in a special file called SWITCH.INI. When MACY11 is run, it will scan the user's search list to find SWITCH.INI. If the file is not found, then standard defaults (as defined elsewhere in this document) are assumed. If SWITCH.INI is found but no MACY11 switches are found, default settings are assumed. To specify defaults, use the editor of your choice to create a file called SWITCH.INI. This file must contain a line of the following format: MACY11/switch1/switch2...../switchn Continuation lines are permitted. Specifically, a line containing a terminal hyphen is assumed to be followed by a continuation line. Of course MACY11 does not consider the hyphen to be a part of any switch. Note that this feature is a subset of the facility offered by DIRECT, SOS and perhaps other cusps.