.lm 8 .rm 72 .c Calling Native Mode Code .s .c From .s .c Compatibility Mode Images .s2 .c Bruce C. Wright .c P. O. Box 3181 .c Duke University Medical Center .c Durham, NC 27710 .s 2 I. Introduction .p Very often, RSX-11M compatibility mode images run into problems for which there is no solution within compatibility mode. For example, if the image has been moved from RSX-11D, IAS, or RSX-11M/PLUS and uses such things as the variable-length send/receive data block (VSDR$ and its relatives), then there is no easy way within the RSX Application Migration Executive (AME) to provide the additional functionality. The AME implements only those operations which exist under RSX-11M, and even then they are not always compatible with the way the equivalent functions are performed under RSX-11M. For example, the spawn task directive (SPWN$) does not work in either an upward or downward compatible fashion under VAX/VMS (and as of VAX/VMS V2.4 still did not operate correctly in any event). .p It should be stressed that the above missing or incompatible directives are by no means a complete list; it isn't even a complete list of the directives whose support under VAX/VMS would be "reasonable." Be forewarned that unless your RSX-11 task is strictly limited to file I/O and does not do any terminal I/O or intertask communication of any kind, it is quite likely that there may be problems moving the code to VAX/VMS. The problems which we addressed via the mechanism to be described are by no means a complete list of the problems which we encountered; the other problems could be corrected by source modifications and conditional assemblies for VMS versus RSX-11. Of course, we have no way of knowing whether we even have a good estimate of the total number of incompatibilities, so even such a list would of necessity be incomplete. .p Because of some of these problems, we had difficulty implementing a large database application under VAX/VMS in compatibility mode. Although we intend to move it to native mode eventually, it was not practical to do so immediately and so we decided to run parts of it in compatibility mode. During our efforts to find a clean solution to all of the problems, we discovered that there is an undocumented facility in the RSX Application Migration Executive which allows native mode code to be executed from a compatibility mode image. Although the interface to this mechanism is not very clean, it is currently the only method of which we are aware which will allow the satisfactory solution of some of these problems and we are placing this in the VAX SIG tape in the hope that other users will not have to go through the grief that we had to go through. .p Amazingly, when we brought the usefulness of this facility to the attention of the VMS development team, we were told that this was not considered to be something which DEC had any commitment to provide in any form, either by a mechanism for calling native mode code, or by a mechanism for adding directives to the AME, or by bringing the AME up to compatibility with the PDP-11 operating systems! Although we have no great emotional commitment to the current implementation, we feel that one of the great weaknesses in the VMS compatibility mode support is that it is not all that compatible, so much so that if all of these methods of providing the missing functionality are blocked by DEC it amounts to the evisceration of compatibility mode. If there are other users who feel as we do, we would like to try to demonstrate to DEC that there is interest in the user community in providing better support for PDP-11 mode on the VAX (possibly using this type of facility) and that it is in their best interest to provide better support for compatibility mode than is currently the case. .s 2 II. Overview .p The basic mechanism used by the AME for implementing this function is for the compatibility mode code to execute an undocumented directive (Directive Identification Code number 145.) which implements a number of miscellaneous functions for compatibility mode. The directive has a variety of forms which do quite different things. For example, it is used to parse VAX/VMS file names, which may involve translating logical names -- a function not directly available in compatibility mode; and to implement the "CHAIN" facility in the compatibility mode BASIC interpreter. .p In the form of the directive which allows execution of native mode code, part of the directive parameter block (DPB) specifies a string which is the name of a VAX/VMS file which contains a native mode image with the code to be executed. This image is loaded into the address space of the process and the AME calls it as a subroutine using a parameter list described in more detail below. The image has the entire data area of the compatibility mode image available (starting at location 0), so with a little care and imagination it is possible to devise a very general parameter passing mechanism between the two modes. It is also possible to link the image with the native mode debugger, in which case DEBUG will be started when the native mode image is loaded, making debugging the image that much easier. .p A set of example files are also in this directory which demonstrate the use of the facility to provide some of the functions available under IAS and which were essential for the operation of the large application mentioned earlier. Unfortunately, the facility is not entirely transparant to the compatibility mode image, but the code for the application was sufficiently modular that the interface subroutines could be replaced without affecting the higher-level code in the system. .s 2 III. Implementation .p The basic format for the directive from the point of view of the compatibility mode image is: .s 1 .nf .nj EXFC: .BYTE 145.,8. ; Directive code and length .WORD 4 ; Subfunction code - Call native ; mode image (other subfunction ; (Other subfunction codes are: ; 0 - "Normal" file parse ; 1 - Device name parse ; 2 - File Name Block parse ; 3 - RMS-11 file parse ; 4 - Native mode execution ; 5 - Return disk geometry ; 6 - Basic+2 chain directive) .WORD SECNAM ; Address of a string with the ; image name to be called. .WORD SECLEN ; Length of the above string. ; ; In the image, the "parameters" from the compatibility mode ; image are usually taken as starting here. This could include ; a pointer to the real argument list or the arguments could ; start immediately. In our implementation, we started with a ; subfunction code for the image, thus: ; .WORD 4 ; Subfunction code for terminal ; driver emulation routines .WORD BUF ; Address of buffer to receive ; terminal status information ; (in RSX-11 format). .WORD BUFLEN ; Length of the terminal status ; buffer above. IOST: .WORD 0,0,0,0 ; VMS I/O status block. ; ; This is the end of the directive block, including the fields ; used by the native mode image. The following areas are the ; auxilliary fields referred to by the above parameter block. ; SECNAM: .ASCII /__DBA0:[1,1]MYFILE.EXE/ ; The image name. SECLEN = .-SECNAM ; Length of image name .EVEN BUF: .BYTE TC.TTP,0 ; Returns terminal type .BYTE TC.WID,0 ; Returns terminal width BUFLEN = .-BUF ; Length of buffer. .s .f .j This directive parameter block (DPB) can be executed in the code for the compatibility mode image like any other directive, as the argument to a DIR$ macro. The $S format will probably be too difficult to deal with because of the rather strange format of the directive. .p The native mode image is called with a parameter list which looks similar to (in higher-level language terms): .s .nf .nj = natvmode (xfer__array, cli__callback, ihd, ifd, linkopt, cliopt, parms) .f .j .s The parameters mean: .list .le XFER__ARRAY - This is the address of the image transfer address array, from the image header descriptor for the image. .le CLI__CALLBACK - This is the address of a CLI callback routine. For this purpose, the callback routine is a dummy routine. .le IHD - The address of the image header descriptor. .le IFD - The address of the image file descriptor. .le LINKOPT - a longword containing link options from the image header descriptor. .le CLIOPT - a longword containing CLI options flags. This is always 0 for this purpose. .le PARMS - The actual parameter list address. .end list The only parameter of any interest is the `parms' parameter. It contains the address of the end of the DPB (noted above as the position of the normal beginning of arguments to the image). It is possible to use some other mechanism for data transfer between compatibility mode and native mode, but the other mechanisms would have to rely on predefined "magic" locations and are consequently less robust. If a large amount of data needs to be moved between the two modes, it is probably better to specify buffer areas as done above; since all handling of the buffers is done by the native mode image (in the same address space as the compatibility mode image), there is no restriction placed on the size of such areas.