HP OpenVMS Systems Documentation

This is a user-written routine that is used in place of the TPU$FILE_SEARCH routine.

Format

FILE_SEARCH result-string ,flags ,filespec ,default-spec ,related-spec

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. If an odd numeric value is returned, the next call to the built-in procedure FILE_SEARCH automatically sets the TPU$M_REPARSE bit in the flags longword. TPU$M_REPARSE is also set if the result-string has a length of 0.

Arguments

result-string

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

Return value for the built-in procedure FILE_SEARCH. Your program should fill in this descriptor with a dynamic string allocated by the string routines such as the Run-Time Library routine LIB$SGET1_DD. DECTPU frees this string when necessary.

The TPU$M_REPARSE bit is set in the flags longword if the result-string has a length of zero. The bit is intended to reset the file search when wildcard searches are performed.

flags

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The following table shows the flags used for specifying the file components:

Flag1	Function
TPU$M_NODE	Requests for the node component of the file specification.
TPU$M_DEV	Requests for the device component of the file specification.
TPU$M_DIR	Requests for the directory component of the file specification.
TPU$M_NAME	Requests for the name component of the file specification.
TPU$M_TYPE	Requests for the type component of the file specification.
TPU$M_VER	Requests for the version component of the file specification.
TPU$M_REPARSE	Reparses the file specification before processing. This is intended as a way to restart the file search. This flag will automatically be set by DECTPU if on a previous call to the FILE_SEARCH user routine the result-string has a zero length or the routine returns a odd (noneven) status.
TPU$M_HEAD	Requests for the NODE, DEVICE, and DIRECTORY components of the file specification.
TPU$M_TAIL	Requests for the NAME, TYPE, and VERSION component of the file specification.

filespec

default-spec

The value 0 is passed if there is no default-spec.

related-spec

The value 0 is passed if there is no related-spec.

Description

The FILE_SEARCH user routine allows an application to replace the TPU$FILE_SEARCH routine with its own file-searching routine. The calling program passes the address of the routine to the TPU$INITIALIZE routine using the TPU$_FILE_SEARCH item code.

When the DECTPU built-in procedure FILE_SEARCH is called from TPU code, DECTPU calls either the user-written FILE_SEARCH routine (if one was passed to TPU$INITIALIZE) or the TPU$FILE_SEARCH routine. The return value of the built-in procedure is the string returned in the result-string argument.

To ensure proper operation of the user's ON_ERROR handlers, errors in the user-written FILE_PARSE routine should be signaled using the TPU$SIGNAL routine.

The user-written HANDLER routine performs condition handling.

Format

HANDLER signal_vector ,mechanism_vector

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value.

Arguments

signal_vector

OpenVMS usage:	arg_list
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Signal vector. See the OpenVMS System Services Reference Manual for information about the signal vector passed to a condition handler.

mechanism_vector

OpenVMS usage:	arg_list
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Mechanism vector. See the OpenVMS System Services Reference Manual for information about the mechanism vector passed to a condition handler.

Description

If you need more information about writing condition handlers and programming concepts, refer to OpenVMS Programming Interfaces: Calling a System Routine.

Instead of writing your own condition handler, you can use the default condition handler, TPU$HANDLER. If you want to write your own routine, you must call TPU$HANDLER with the same parameters that your routine received to handle DECTPU internal signals.

The user-written initialization callback routine is passed to TPU$INITIALIZE as a bound procedure value and called to supply information needed to initialize DECTPU.

Format

INITIALIZE [user_arg]

RETURNS

OpenVMS usage:	item_list
type:	longword (unsigned)
access:	read only
mechanism:	by reference

This routine returns the address of an item list.

Arguments

user_arg

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

User argument.

Description

The user-written initialization callback routine is passed to TPU$INITIALIZE as a bound procedure value and called to supply information needed to initialize DECTPU.

If the user_arg parameter was specified in the call to TPU$INITIALIZE, the initialization callback routine is called with only that parameter. If user_arg was not specified in the call to TPU$INITIALIZE, the initialization callback routine is called with no parameters.

The user_arg parameter is provided to allow an application to pass information through TPU$INITIALIZE to the user-written initialization routine. DECTPU does not interpret this data in any way.

The user-written callback routine is expected to return the address of an item list containing initialization parameters. Because the item list is used outside the scope of the initialization callback routine, it should be allocated in static memory.

The item list entries are discussed in the section on TPU$INITIALIZE. Most of the initialization parameters have a default value; strings default to the null string, and flags default to false. The only required initialization parameter is the address of a routine for file I/O. If an entry for the file I/O routine address is not present in the item list, TPU$INITIALIZE returns with a failure status.

The user-written USER routine allows your program to take control during a DECTPU editing session (for example, to leave the editor temporarily and perform a calculation).

Format

USER integer ,stringin ,stringout

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value.

Arguments

integer

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

First parameter to the built-in procedure CALL_USER. This is an input-only parameter and must not be modified.

stringin

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by descriptor

Second parameter to the built-in procedure CALL_USER. This is an input-only parameter and must not be modified.

stringout

OpenVMS usage:	char_string
type:	character string
access:	modify
mechanism:	by descriptor

Return value for the built-in procedure CALL_USER. Your program should fill in this descriptor with a dynamic string allocated by the string routines (such as LIB$SGET1_DD) provided by the Run-Time Library. The DECTPU editor frees this string when necessary.

Description

This user-written routine is invoked by the DECTPU built-in procedure CALL_USER. The built-in procedure CALL_USER passes three parameters to this routine. These parameters are then passed to the appropriate part of your application to be used as specified. (For example, they can be used as operands in a calculation within a Fortran program.) Using the string routines provided by the Run-Time Library, your application fills in the stringout parameter in the call-user routine, which returns the stringout value to the built-in procedure CALL_USER.

The description of the built-in procedure CALL_USER in the DEC Text Processing Utility Reference Manual shows an example of a BASIC program that is a call-user routine.

See Section 8.5 for a description of how to create an executeable image for the USER routine and how to call the routine from a C program in the DECTPU environment.

On OpenVMS operating systems, the EDT editor can be called from a program written in any language that generates calls using the OpenVMS Calling Standard.

You can set up your call to EDT so the program handles all the editing work, or you can make EDT run interactively so you can edit a file while the program is running.

This chapter on callable EDT assumes that you know how to call an external facility from the language you are using. Callable EDT is a shareable image, which means that you save physical memory and disk space by having all processes access a single copy of the image.

9.1 Introduction to EDT Routines

You must include a statement in your program accessing the EDT entry point. This reference statement is similar to a library procedure reference statement. The EDT entry point is referenced as EDT$EDIT. You can pass arguments to EDT$EDIT; for example, you can pass EDT$FILEIO or your own routine. When you refer to the routines you pass, call them FILEIO, WORKIO, and XLATE. Therefore, FILEIO can be either a routine provided by EDT (named EDT$FILEIO) or a routine that you write.

9.2 Using the EDT Routines: An Example

Example 9-1 shows a VAX BASIC program that calls EDT. All three routines (FILEIO, WORKIO, and XLATE) are called. Note the reference to the entry point EDT$EDIT in line number 500.

100  EXTERNAL INTEGER EDT$FILEIO  (1)
200  EXTERNAL INTEGER EDT$WORKIO
250  EXTERNAL INTEGER AXLATE
300  EXTERNAL INTEGER FUNCTION EDT$EDIT
400  DECLARE INTEGER RESULT


450  DIM INTEGER PASSFILE(1%)  (2)
460  DIM INTEGER PASSWORK(1%)
465  DIM INTEGER PASSXLATE(1%)
470  PASSFILE(0%) = LOC(EDT$FILEIO)
480  PASSWORK(0%) = LOC(EDT$WORKIO)
485  PASSXLATE(0%) = LOC(AXLATE)

500  RESULT = EDT$EDIT('FILE.BAS','','EDTINI','',0%,  (3)
     PASSFILE(0%)BY REF, PASSWORK(0%) BY REF, (4)
     PASSXLATE(0%) BY REF)  (5)
600  IF (RESULT AND 1%) = 0%
     THEN
       PRINT "SOMETHING WRONG"
       CALL LIB$STOP(RESULT BY VALUE)
900  PRINT "EVERYTHING O.K."
1000 END

1. The external entry points EDT$FILEIO, EDT$WORKIO, and AXLATE are defined so they can be passed to callable EDT.
2. Arrays are used to construct the two-longword structure needed for data type BPV.
3. Here is the call to EDT. The input file is FILE.BAS, the output and journal files are defaulted, and the command file is EDTINI. A 0 is passed for the options word to get the default EDT options.
4. The array PASSFILE points to the entry point for all file I/O, which is set up in this example to be the EDT-supplied routine with the entry point EDT$FILEIO. Similarly, the array PASSWORK points to the entry point for all work I/O, which is the EDT-supplied routine with the entry point EDT$WORKIO.
5. PASSXLATE points to the entry point that EDT will use for all XLATE processing. PASSXLATE points to a user-supplied routine with the entry point AXLATE.

This section describes the individual EDT routines.

The EDT$EDIT routine invokes the EDT editor.

Format

EDT$EDIT in_file [,out_file] [,com_file] [,jou_file] [,options] [,fileio] [,workio] [,xlate]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

in_file

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

File specification of the input file that EDT$EDIT is to edit. The in_file argument is the address of a descriptor pointing to this file specification. The string that you enter in this calling sequence is passed to the FILEIO routine to open the primary input file. This is the only required argument.

out_file

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

File specification of the output file that EDT$EDIT creates. The out_file argument is the address of a descriptor pointing to this file specification. The default is that the input file specification is passed to the FILEIO routine to open the output file for the EXIT command.

com_file

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

File specification of the startup command file to be executed when EDT is invoked. The com_file argument is the address of a descriptor pointing to this file specification. The com_file string is passed to the FILEIO routine to open the command file. The default is the same as that for EDT command file defaults.

jou_file

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by descriptor

File specification of the journal file to be opened when EDT is invoked. The jou_file argument is the address of a descriptor pointing to this file specification. The jou_file string is passed to the FILEIO routine to open the journal file. The default is to use the same file name as in_file.

options

OpenVMS usage:	mask_longword
type:	aligned bit string
access:	read only
mechanism:	by reference

Bit vector specifying options for the edit operation. The options argument is the address of an aligned bit string containing this bit vector. Only bits <5:0> are currently defined; all others must be 0. The default options have all bits set to 0. This is the same as the default setting when you invoke EDT to edit a file from DCL.

Symbols and their descriptions follow:

Symbol	Description
EDT$M_RECOVER	If set, bit <0> causes EDT to read the journal file and execute the commands in it, except for the EXIT or QUIT commands, which are ignored. After the journal file commands are processed, editing continues normally. If bit <0> is set, the FILEIO routine is asked to open the journal file for both input and output; otherwise FILEIO is asked only to open the journal file for output. Bit <0> corresponds to the /RECOVER qualifier on the EDT command line.
EDT$M_COMMAND	If set, bit <1> causes EDT to signal if the startup command file cannot be opened. When bit <1> is 0, EDT intercepts the signal from the FILEIO routine indicating that the startup command file could not be opened. Then, EDT proceeds with the editing session without reading any startup command file. If no command file name is supplied with the call to the EDT$EDIT routine, EDT tries to open SYS$LIBRARY:EDTSYS.EDT or, if that fails, EDTINI.EDT. Bit <1> corresponds to the /COMMAND qualifier on the EDT command line. If EDT$M_NOCOMMAND (bit <4>) is set, bit <1> is overridden because bit <4> prevents EDT from trying to open a command file.
EDT$M_NOJOURNAL	If set, bit <2> prevents EDT from opening the journal file. Bit <2> corresponds to the /NOJOURNAL or /READ_ONLY qualifier on the EDT command line.
EDT$M_NOOUTPUT	If set, bit <3> prevents EDT from using the input file name as the default output file name. Bit <3> corresponds to the /NOOUTPUT or /READ_ONLY qualifier on the EDT command line.
EDT$M_NOCOMMAND	If set, bit <4> prevents EDT from opening a startup command file. Bit <4> corresponds to the /NOCOMMAND qualifier on the EDT command line.
EDT$M_NOCREATE	If set, bit <5> causes EDT to return to the caller if the input file is not found. The status returned is the error code EDT$_INPFILNEX.

fileio

OpenVMS usage:	vector_longword_unsigned
type:	bound procedure value
access:	function call
mechanism:	by reference

User-supplied routine called by EDT to perform file I/O functions. The fileio argument is the address of a bound procedure value containing the user-supplied routine. When you do not need to intercept any file I/O, either use the entry point EDT$FILEIO for this argument or omit it. When you only need to intercept some amount of file I/O, call the EDT$FILEIO routine for the other cases.

To avoid confusion, note that EDT$FILEIO is a routine provided by EDT whereas FILEIO is a routine that you provide.

In order to accommodate routines written in high-level languages that do up-level addressing, this argument must have a data type of BPV (bound procedure value). BPV is a two-longword entity in which the first longword contains the address of a procedure value and the second longword is the environment value. When the bound procedure is called, EDT loads the second longword into R1. If you use EDT$FILEIO for this argument, set the second longword to <0>. You can pass a <0> for the argument, and EDT will set up EDT$FILEIO as the default and set the environment word to 0.

workio

OpenVMS usage:	vector_longword_unsigned
type:	bound procedure value
access:	function call
mechanism:	by reference

User-supplied routine called by EDT to perform I/O between the work file and EDT. The workio argument is the address of a bound procedure value containing the user-supplied routine. Work file records are addressed only by number and are always 512 bytes long. If you do not need to intercept work file I/O, you can either use the entry point EDT$WORKIO for this argument or omit it.

In order to accommodate routines written in high-level languages that do up-level addressing, this argument must have a data type of BPV (bound procedure value). This means that EDT loads R1 with the second longword addressed before calling it. If EDT$WORKIO is used for this argument, set the second longword to 0. You can pass a 0 for this argument, and EDT will set up EDT$WORKIO as the default and set the environment word to 0.

xlate

OpenVMS usage:	vector_longword_unsigned
type:	bound procedure value
access:	function call
mechanism:	by reference

User-supplied routine that EDT calls when it encounters the nokeypad command XLATE. The xlate argument is the address of a bound procedure value containing the user-supplied routine. The XLATE routine allows you to gain control of your EDT session. If you do not need control of EDT during the editing session, you can either use the entry point EDT$XLATE for this argument or omit it.

In order to accommodate routines written in high-level languages that do up-level addressing, this argument must have a data type of BPV (bound procedure value). This means that EDT loads R1 with the second longword addressed before calling it. If EDT$XLATE is used for this argument, set the second longword to 0. You can pass a 0 for this argument, and EDT will set up EDT$XLATE as the default and set the environment word to 0.

Description

If the EDT session is terminated by EXIT or QUIT, the status will be a successful value (bit <0> = 1). If the session is terminated because the file was not found and if the /NOCREATE qualifier was in effect, the failure code EDT$_INPFILNEX is returned. In an unsuccessful termination caused by an EDT error, a failure code corresponding to that error is returned. Each error status from the FILEIO and WORKIO routines is explained separately.

Three of the arguments to the EDT$EDIT routine, fileio, workio, and xlate are the entry point names of user-supplied routines.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
EDT$_INPFILNEX	/NOCREATE specified and input file does not exist.