From: Chris_F_Chiesa@cup.portal.com
Newsgroups: comp.os.vms
Subject: Long-awaited $IMGACT example program, part 1 of 2
Date: Wed,  6 Jan 93 18:51:45 PST
Organization: The Portal System (TM)
Distribution: world

$! ------------------ CUT HERE -----------------------
$ v='f$verify(f$trnlnm("SHARE_VERIFY"))'
$!
$! This archive created by VMS_SHARE Version 7.2-007  22-FEB-1990
$!   On 17-DEC-1992 15:38:06.33   By user CHIESA 
$!
$! This VMS_SHARE Written by:
$!    Andy Harper, Kings College London UK
$!
$! Acknowledgements to:
$!    James Gray       - Original VMS_SHARE
$!    Michael Bednarek - Original Concept and implementation
$!
$!+ THIS PACKAGE DISTRIBUTED IN 2 PARTS, TO KEEP EACH PART
$!  BELOW 30 BLOCKS
$!
$! TO UNPACK THIS SHARE FILE, CONCATENATE ALL PARTS IN ORDER
$! AND EXECUTE AS A COMMAND PROCEDURE  (  @name  )
$!
$! THE FOLLOWING FILE(S) WILL BE CREATED AFTER UNPACKING:
$!       1. README.TXT;7
$!       2. TRYIT.MAR;22
$!       3. TRYIT.OPT;1
$!       4. TRYIT.CLD;7
$!
$set="set"
$set symbol/scope=(nolocal,noglobal)
$f=f$parse("SHARE_TEMP","SYS$SCRATCH:.TMP_"+f$getjpi("","PID"))
$e="write sys$error  ""%UNPACK"", "
$w="write sys$output ""%UNPACK"", "
$ if f$trnlnm("SHARE_LOG") then $ w = "!"
$ ve=f$getsyi("version")
$ if ve-f$extract(0,1,ve) .ges. "4.4" then $ goto START
$ e "-E-OLDVER, Must run at least VMS 4.4"
$ v=f$verify(v)
$ exit 44
$UNPACK: SUBROUTINE ! P1=filename, P2=checksum
$ if f$search(P1) .eqs. "" then $ goto file_absent
$ e "-W-EXISTS, File ''P1' exists. Skipped."
$ delete 'f'*
$ exit
$file_absent:
$ if f$parse(P1) .nes. "" then $ goto dirok
$ dn=f$parse(P1,,,"DIRECTORY")
$ w "-I-CREDIR, Creating directory ''dn'."
$ create/dir 'dn'
$ if $status then $ goto dirok
$ e "-E-CREDIRFAIL, Unable to create ''dn'. File skipped."
$ delete 'f'*
$ exit
$dirok:
$ w "-I-PROCESS, Processing file ''P1'."
$ if .not. f$verify() then $ define/user sys$output nl:
$ EDIT/TPU/NOSEC/NODIS/COM=SYS$INPUT 'f'/OUT='P1'
PROCEDURE Unpacker ON_ERROR ENDON_ERROR;SET(FACILITY_NAME,"UNPACK");SET(
SUCCESS,OFF);SET(INFORMATIONAL,OFF);f:=GET_INFO(COMMAND_LINE,"file_name");b:=
CREATE_BUFFER(f,f);p:=SPAN(" ")@r&LINE_END;POSITION(BEGINNING_OF(b));
LOOP EXITIF SEARCH(p,FORWARD)=0;POSITION(r);ERASE(r);ENDLOOP;POSITION(
BEGINNING_OF(b));g:=0;LOOP EXITIF MARK(NONE)=END_OF(b);x:=ERASE_CHARACTER(1);
IF g=0 THEN IF x="X" THEN MOVE_VERTICAL(1);ENDIF;IF x="V" THEN APPEND_LINE;
MOVE_HORIZONTAL(-CURRENT_OFFSET);MOVE_VERTICAL(1);ENDIF;IF x="+" THEN g:=1;
ERASE_LINE;ENDIF;ELSE IF x="-" THEN IF INDEX(CURRENT_LINE,"+-+-+-+-+-+-+-+")=
1 THEN g:=0;ENDIF;ENDIF;ERASE_LINE;ENDIF;ENDLOOP;t:="0123456789ABCDEF";
POSITION(BEGINNING_OF(b));LOOP r:=SEARCH("`",FORWARD);EXITIF r=0;POSITION(r);
ERASE(r);x1:=INDEX(t,ERASE_CHARACTER(1))-1;x2:=INDEX(t,ERASE_CHARACTER(1))-1;
COPY_TEXT(ASCII(16*x1+x2));ENDLOOP;WRITE_FILE(b,GET_INFO(COMMAND_LINE,
"output_file"));ENDPROCEDURE;Unpacker;QUIT;
$ delete/nolog 'f'*
$ CHECKSUM 'P1'
$ IF CHECKSUM$CHECKSUM .eqs. P2 THEN $ EXIT
$ e "-E-CHKSMFAIL, Checksum of ''P1' failed."
$ ENDSUBROUTINE
$START:
$ create 'f'
XREADME.TXT for "Call VMS COPY" demo, December 17, 1992
XChris Chiesa
XChris_F_Chiesa@cup.portal.com
X
XPosted to "comp.os.vms" aka "INFO-VAX" newsgroup.
X-------
X
XINTRODUCTION:
X
XSeveral weeks ago I posted that I wished to recreate or incorporate the`20
Xfunctionality of the DCL COPY command into a program of my own that added`20
Xsome "front end" criteria to the file-accessibility check phase.  In a`20
Xnutshell, I wanted the "callable COPY" facility so often asked for, and to`2
V0
Xdate omitted, in VMS.
X
XTo make a long story short, when I found that there was no supported way to`
V20
Xcall DCL COPY (SYS$SYSTEM:COPY.EXE) from within a program, I naturally had`2
V0
Xto develop my own.  In this I succeeded, with a little help from the Net,`20
Xand a number of Netters have since expressed interest in seeing the`20
Xresulting "little demo program."  This posting is that program, in a`20
Xpackage with some additional relevant information.
X
X
XOVERVIEW:
X
XTRYIT.MAR is a program which invokes the actual VMS COPY utility -- the`20
Xsame one invoked by the DCL COPY command -- to copy files.  TRYIT is`20
Xinvoked by the command verb TRYIT, whose syntax is, for all intents and`20
Xpurposes, the same as the DCL COPY command.  (The sharp-eyed reader will`20
Xnote, however, that TRYIT's "Command Language Definition" is nearly`20
Xtrivial.  <wink>)
X
XTRYIT accomplishes this amazing feat by using several of what I consider`20
Xthe more esoteric capabilities of VMS, including one or two which aren't`20
Xofficially "supported."  They exist, though, and can be used as long as you`
V20
Xdon't mind being outside the graces of Digital...
X
XBUILDING AND TRYING "TRYIT":
X
XSetting up to see TRYIT do its thing is a -step process.  First you have to`
V20
Xextract the various files which comprise the package, which you've already`2
V0
Xdone if you're reading this!  The shipping manifest looks like this:
X
X`09README.TXT `09- this file
X`09TRYIT.MAR`09- Macro-32 source code
X`09TRYIT.OPT`09- Linker options file
X`09TRYIT.CLD`09- TRYIT command definition
X
XFor best results, leave all of these files in your default directory.
X
XSecond, assemble TRYIT.MAR to form the object TRYIT.OBJ:
X
X`09$ MACRO TRYIT
X
XThird, link TRYIT.OBJ to form the executable image TRYIT.EXE:
X
X`09$ LINK TRYIT,TRYIT/OPT
X
X... yes, that's right, the word TRYIT appears TWICE.  It's not a typo.
X
XFourth, give yourself the TRYIT command:
X
X`09$ SET COMMAND TRYIT
X
XFifth, define the logical name "TESTDIR" to point to your current default
Xdirectory (or wherever you've placed TRYIT.EXE).  If this IS your current
Xdirectory, the following command will do the deed:
X
X`09$ DEFINE TESTDIR 'F$ENV("DEFAULT")
X
XFinally, try it!  (Hence the name.)  Make up a DCL COPY command you'd like
Xto execute, but instead of the verb COPY, use the verb TRYIT!  You'll see
Xa message from TRYIT, then your copy will take place (to see it happen, use`
V20
Xthe /LOG qualifier), then you'll see another message fom TRYIT, showing`20
Xthat it regained control after the COPY operation.  That's all, folks!
X
X
XAPPENDIX A: FACILITIES AND TOOLS USED
X
XFor details as to the step-by-step operation of the program, see the`20
Xcomments in source file TRYIT.MAR.  If that still doesn't do it for you,`20
Xwrite me at the Internet mail address given at the start of this document.
X
XThe facilities and tools which went into the creation of TRYIT are as`20
Xfollows:
X
X`09VMS Utilities:
X`09`09ANALYZE/IMAGE`09
X`09`09`09- before writing the TRYIT.MAR source code, to`20
X`09`09`09  discover the Universal symbol (DCL$AL_TAB_VEC)`20
X`09`09`09  representing the address of the command table in
X`09`09`09  a DCL table image file`20
X
X`09System Services:
X
X`09`09$GETJPI`09- to obtain the Username of the process running`20
X`09`09`09  TRYIT, as food for $GETUAI
X`09`09$GETUAI - to obtain the name of the default DCL command`20
X`09`09`09  table of the process running TRYIT
X`09`09$IMGACT`09- UNDOCUMENTED/UNSUPPORTED! to merge SYS$SYSTEM:
X`09`09`09  COPY.EXE into TRYIT's address space where it
X`09`09`09  could be invoked as a procedure call
X`09`09$IMGFIX`09- UNDOCUMENTED/UNSUPPORTED! goes with $IMGACT
X
X
X`09Run-Time Library Routines:
X
X`09`09LIB$FIND_IMAGE_SYMBOL -
X`09`09`09  to find the command table that defines the DCL`20
X`09`09`09  COPY command, and bring that table into TRYIT's`20
X`09`09`09  address space for the CLI$ routines to use
X`09`09LIB$PUT_OUTPUT -
X`09`09`09  to display a message before and after calling
X`09`09`09  VMS COPY, to prove that TRYIT has control both
X`09`09`09  before and after that event
X`09`09STR$CONCAT -
X`09`09`09  to construct a fake command line, by prefixing
X`09`09`09  the COPY verb to the tail of the TRYIT command`20
X`09`09`09  line
X`09`09
X
X`09Utility Routines:
X
X`09`09CLI$DCL_PARSE -
X`09`09`09  to operate on the fake COPY command as DCL would
X`09`09`09  normally do for a real one, before calling`20
X`09`09`09  COPY.EXE
X`09`09CLI$GET_VALUE -
X`09`09`09  to obtain command-line values, first from the
X`09`09`09  real DCL command line, then from a fake command
X`09`09`09  line constructed to fool COPY into being happy
X
XNote that all but the $IMGACT / $IMGFIX system service usages here are`20
Xfully documented and supported; it's a shame that this technique should be`2
V0
X"so near and yet so far" from full supportability.
X
XAPPENDIX B: SOURCE OF INSPIRATION
X
XI believe my first posting on this subject may have mentioned that the idea`
V20
Xfor this program came "from a posting in this very newsgroup a long time`20
Xago," whose date, author, etc. were now lost to me.  Well, you're all in`20
Xfor a special treat, because guess what I found this morning while cleaning`
V20
Xout an old notebook?  That original "posting... (from) a long time ago!"`20
XI find that it first appeared on the Net nearly four and a half years ago;`2
V0
Xat the time I first read it I was still a college student, and lacked much`2
V0
Xof the background necessary to understand what it was talking about.  But I`
V20
Xsaved it, and over the subsequent four years gained enough VMS knowledge to`
V20
Xfinally put all the pieces together and make it work.  Without further ado,`
V20
Xthen, I here reproduce that inspirational "original posting," in its`20
Xentirety.  Thanks very much to you, Garry Wiegand, if you're reading this!
X
X---- INCLUDED TEXT BEGINS ----
X
XFrom: garry@batcomputer.tn.cornell.edu (Garry Wiegand)
XNewsgroups: comp.os.vms
XSubject: Re: Chaining images... THE source
XDate: 28 Mar 88 02:17:22 GMT
XOrganization: Cornell Engineering && Ithaca Software, Inc.
X
XIn a recent article carl@CITHEX.CALTECH.EDU (Carl J Lydick) wrote:
X>I'm one of the people who referred you to LIB$FIND_IMAGE_SYMBOL.  Let me po
Vint
X>out again that this works only with SHAREABLE images.  This means that you
X>can't chain most images that are linked to be run via a command from the DC
VL
X>level...
X
XNow, if you want to be a real wiz, what you do is:
X
XA) get your DCL command line from wherever and nibble off the command verb.
X   Either use a hard lookup table (ie, "DELE" -> SYS$SYSTEM:DELETE) or
X   a program like Verb as a subroutine to find the right image to activate.
XB) Activate that image with SYS$IMGACT - it doesn't have to be a shareable
X   image.
XC) call Find_Image_Symbol on DCLTABLES.EXE to get the address of the real
X   DCL tables (the name I forget, use ANAL/IMAGE to see it) (the tables are
X   up in P1 space too, I think, if you prefer)
XD) Tell CLI to parse up the command line please
XE) Call the entry point of DELETE, DIRECTORY, or whoever the image turned
X   out to be *as a subroutine*.  It don't know/can't tell that it isn't
X   running as a normal DCL call, calls CLI like usual, and everything works
X   out.
X
XI leave trapping out possible SYS$EXIT calls from the called program as an
Xexercise for the reader.
X
XI used to have the code for this and a bunch of other nonsense 3-4 years,
Xbut I just looked around in all the dusty places and don't see it
Xanymore.  ((Before we got involved in graphics, we were playing some`20
Xideas for some new VMS utilities.  I got involved in the above in the`20
Xcourse of adding an some new switches/abilities to existing VMS commands -
XI could have just duplicated the previous VMS functionality and gone
Xon, but that was tedious and I also didn't want to have to *keep*`20
Xduplicating DEC's functionality.  So we just used Dec's programs as
Xsubroutines of our own.))
X
XOh, the functionality involved was the "UNDELETE" command, with related
Xswitches DIR/DELETED, DELETE/REALLY, etc etc etc.  All blended in
Xnicely. Cute.  (Normal-delete became a surreptious Rename to an invisible
Xparallel directory tree.)
X
XNever did get around to trying to sell the various things - people still
Xare just barely interested in non-Dec *hardware* - VMS add-on software
Xwas/is an even tougher row to hoe.
X
Xgarry wiegand   (garry@oak.cadif.cornell.edu - ARPA)
X                (garry@crnlthry - BITNET)
X
X----- END INCLUDED TEXT -----
X
X
XAPPENDIX C: $IMGACT AND $IMGFIX
X
XNaturally, I suppose you'll want to know how I found out, or figured out,`20
Xhow to use $IMGACT if it's not documented.  Well, it turns out that $IMGACT`
V20
X_is_ documented, sort of.  The FORTRAN header files for system symbol`20
Xdefinition turn out to contain a little paragraph about $IMGACT (and`20
X$IMGFIX), and there's a word or two in the various releases of the VAX/VMS`2
V0
XInternals And Data Structures books that have come out over time.
X
XFor the sake of your enlightenment, appended find a copy of *all* the`20
Xinformation I have ever received about $IMGACT / $IMGFIX.
X
X----- INCLUDED TEXT BEGINS -----
X---- IMGACT_1.TXT ----
X!   $IMGACT
X!`20
X!     Image Activation
X!`20
X!      $IMGACT`09name,`5Bdflnam`5D,hdrbuf,`5Bimgctl`5D,`5Binadr`5D,
X! `09`09`5Bretadr`5D, `5Bident`5D, `5Bacmode`5D
X!`20
X!`20
X!      name`09= address of descriptor for file name string
X!`20
X!      dflnam`09= descriptor for file name string
X!`20
X!      hdrbuf`09= address of 512 byte buffer to write in
X!`20
X!      imgctl`09= image activation control flags
X!`20
X!      inadr`09= address of quadword specifying virtual address
X! `09`09  range to be mapped
X!`20
X!      retadr`09= address of quadword specifying virtual address
X! `09`09  range actually mapped
X!                                    `20
X!      ident`09= address of quadword holding image section match
X! `09`09  control and identifier
X!`20
X!      acmode`09= access mode to be the owner of the created pages
X!`20
X`09INTEGER*4 SYS$IMGACT
X`09EXTERNAL  SYS$IMGACT
X!   $IMGFIX
X!`20
X!     Image Address Fixup Service
X!`20
X!      $IMGFIX                       `20
X!`20
X`09INTEGER*4 SYS$IMGFIX
X`09EXTERNAL  SYS$IMGFIX
X
X---- IMGACT_2.TXT ----
X
X--- Begin Quoting VAX/VMS Internals and Data Structures, CH 21.1, pp 465-467
V ---
Xname`09string descriptor of image that is being activated
Xdflnam`09string descriptor for default file name
Xhdrbuf`09Address of 512-byte buffer in which the image header and image
X`09file descriptor are returned. The first two longwords in the buffer
X`09are the addresses (within the buffer) of the image header and the
X`09image file descriptor respectively
Ximgctl`09Image activation control flags. These flags control the form the th
Ve
X`09activation file will take. The options are the following:
X`09Flag`09`09Meaning
X`09IAC$V_NOACT`09If set, the image activator is not to activate the
X`09`09`09image. This flag is used by the Install Utility to
X`09`09`09complete the installation of known file entries
+-+-+-+-+-+-+-+-  END  OF PART 1 +-+-+-+-+-+-+-+-
Newsgroups: comp.os.vms