The TPU$INITIALIZE routine initializes TPU for text
processing. This routine allocates global data structures,
initializes global variables, and calls the appropriate setup
routines for each of the major components of the editor,
including the Screen Manager and the I/O subsystem.
Format
TPU$INITIALIZE callback [,user_arg]
1 – 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.
2 – Argument
callback
OpenVMS usage:vector_longword_unsigned
type: bound procedure value
access: read only
mechanism: by descriptor
Callback routine. The callback argument is the address of a
user-written routine that returns the address of an item list
containing initialization parameters or a routine for handling
file I/O operations. This callback routine must call a command
line parsing routine, which can be TPU$CLIPARSE or a user-written
parsing routine.
Callable TPU defines item codes that you can use to specify
initialization parameters. The following rules must be followed
when building the item list:
o If you use the TPU$_OTHER_FILENAMES item code, it must follow
the TPU$_FILENAME item code.
o If you use either the TPU$_CHAIN item code or the TPU$_ENDLIST
code, it must be the last item code in the list.
The following figure shows the general format of an item
descriptor. For information about how to build an item list,
refer to the programmer's manual associated with the language
you are using. Any reference to command line qualifiers refer
to those command line qualifiers that you use with the EDIT/TPU
command.
---------------------------------------------
| Item code | Buffer length |
---------------------------------------------
| Buffer address |
---------------------------------------------
| Return address |
---------------------------------------------
The return address in an item descriptor is usually 0.
The following item codes are available:
Item Code Description
TPU$_OPTIONS Enables the command qualifiers. The bits in
the bit mask specified by the buffer address
field correspond to the various TPU command
qualifiers.
TPU$_JOURNALFILE Passes the string specified with the /JOURNAL
qualifier. The buffer length field is the
length of the string, and the buffer address
field is the address of the string. This
string is available with GET_INFO (COMMAND_
LINE,"JOURNAL_FILE"). This string can be a null
string.
TPU$_SECTIONFILE Passes the string that is the name of the
binary initialization file (section file) to
be mapped in. The buffer length field is the
length of the string, and the buffer address
field is the address of the string. If the
TPU$V_SECTION bit is set, this item code must
be specified.
TPU$_OUTPUTFILE Passes the string specified with the /OUTPUT
qualifier. The buffer length field is the
length of the string, and the buffer address
field specifies the address of the string. This
string is returned by the built-in procedure
GET_INFO (COMMAND_LINE, "OUTPUT_FILE"). The
string can be a null string.
TPU$_DISPLAYFILE Passes the string specified with the /DISPLAY
qualifier. The buffer length field defines the
length of the string, and the buffer address
field defines the string address. The interface
between the TPUSHR image and the display file
image is not documented. Applications should
only use this option with documented display
files such as TPU$CCTSHR or TPU$MOTIFSHR.
TPU$_COMMANDFILE Passes the string specified with the /COMMAND
qualifier. The buffer length field is the
length of the string, and the buffer address
field is the address of the string. This string
is returned by the built-in procedure GET_INFO
(COMMAND_LINE, "COMMAND_FILE"). The string can
be a null string.
TPU$_FILENAME Passes the string that is the name of the first
input file specified on the command line.
The buffer length field specifies the length
of this string, and the buffer address field
specifies its address. This string is returned
by the built-in procedure GET_INFO (COMMAND_
LINE, "FIRST_FILE_NAME"). This file name can be
a null string.
TPU$_OTHER_ Passes a string that contains the name of an
FILENAMES input file that follows the first input file
on the command line. The buffer length field
specifies the length of this string, and the
buffer address field specifies its address.
Each additional file specified on the command
line requires its own TPU$_OTHER_FILENAMES item
entry. These strings are returned by the GET_
INFO (COMMAND_LINE,"NEXT_FILE_NAME") built-
in procedure in the order they appear in the
item list. This item code must appear after the
TPU$_FILENAME item in the item list.
TPU$_FILEIO Passes the bound procedure value of a routine
to be used for handling file operations.
You can provide your own file I/O routine,
or you can call TPU$FILEIO, the utility
routine provided by TPU for handling file
operations. The buffer address field specifies
the address of a two-longword vector. The first
longword of the vector contains the address of
the routine. The second longword specifies the
environment value that TPU loads into R1
before calling the routine.
TPU$_CALLUSER Passes the bound procedure value of the user-
written routine that the built-in procedure
CALL_USER is to call. The buffer address field
specifies the address of a two-longword vector.
The first longword of the vector contains the
address of the routine. The second longword
specifies the environment value that TPU
loads into R1 before calling the routine.
TPU$_INIT_FILE Passes the string specified with the
/INITIALIZATION qualifier. The buffer length
field is the length of the string, and the
buffer address field is the address of the
string. This string is returned by the built-in
procedure GET_INFO (COMMAND_LINE,"INIT_FILE").
TPU$_START_LINE Passes the starting line number for the edit.
The buffer address field contains the first of
the two integer values you specified as part
of the /START_POSITION command qualifier. The
value is available using the built-in procedure
GET_INFO (COMMAND_LINE,"LINE"). Usually an
initialization procedure uses this information
to set the starting position in the main
editing buffer. The first line in the buffer
is line 1.
TPU$_START_CHAR Passes the starting column position for the
edit. The buffer address field contains
the second of the two integer values you
specified as part of the /START_POSITION
command qualifier. The value is available
using the built-in procedure GET_INFO (COMMAND_
LINE, "CHARACTER"). Usually an initialization
procedure uses this information to set the
starting position in the main editing buffer.
The first column on a line to character 1.
TPU$_ Passes the string specified with the
CHARACTERSET /CHARACTER_SET qualifier. The buffer length
field specifies the string length and the
buffer address field specifies the string
address. Valid strings are "DEC_MCS" (the
default value), "ISO_LATIN1", and "GENERAL".
If the application tries to pass any other
string, the routine signals an error and passes
the default string (DEC_MCS).
TPU$_WORKFILE Passes the string specified with the /WORK
qualifier. The buffer length field specifies
the string length and the buffer address
specifies the string address. This string is
available with GET_INFO (COMMAND_LINE, "WORK_
FILE").
TPU$_CHAIN Passes the address of the next item list to the
process specified by the buffer address field.
TPU$_ENDLIST Signals the end of the item list.
TPU$_PARENT_ Passes the appropriate parent widget when
WIDGET invoking the DECwindows version of the
editor. This routine is not specified by the
application; TPU invokes its own application
shell. The widget address is passed in the
buffer address field. This item code is only
valid when using the DECwindows interface.
TPU$_ Passes the application context to use with the
APPLICATION_ TPU$_PARENT_WIDGET. TPU defaults to its own
CONTEXT application context. The buffer address field
specifies the application context address.
This item code is only valid when using the
DECwindows interface.
TPU$_ Specifies which file TPU uses to initialize
DEFAULTSFILE the X defaults database. The buffer length
field specifies the string length and the
buffer address field specifies the string
address. This item code is only valid when
using the DECwindows interface.
TPU$_CTRL_C_ Passes the bound procedure value of a routine
ROUTINE to be used for handling Ctrl/C asynchronous
system traps (ASTs). TPU calls the routine
when a Ctrl/C AST occurs. If the routine
returns a FALSE value, TPU assumes that
the Ctrl/C has been handled. If the routine
returns a TRUE value, TPU aborts any
currently executing TPU procedure. The
buffer address field specifies the address
of a two-longword vector. The first longword of
the vector contains the address of the routine.
The second longword specifies the environment
value that TPU loads into R1 before calling
the routine.
TPU$_DEBUGFILE Passes the string specified with the /DEBUG
command qualifier. The buffer length field
is the length of the string, and the buffer
address field is the address of the string.
TPU$_FILE_SEARCH Passes the bound procedure value of a routine
to be used to replace the TPU$FILE_SEARCH
routine which is called when the built-in
procedure FILE_SEARCH is called from TPU code.
See the description of the TPU$FILE_SEARCH
and the user routine FILE_SEARCH for more
information.
TPU$_FILE_PARSE Passes the bound procedure value of a routine
to be used to replace the TPU$FILE_PARSE
routine which is called when the built-
in procedure FILE_PARSE is called from TPU
code. See the description of the TPU$FILE_
PARSE and the user routine FILE_PARSE for more
information.
Valid Masks for the TPU$K_OPTIONS Item Code lists the bits and
corresponding masks enabled by the item code TPU$K_OPTIONS and
shows how each bit affects TPU$INITIALIZE operation. Several bits
in the TPU$_OPTIONS mask require additional item code entries in
the item list. An example of this is TPU$M_COMMAND which requires
a TPU$_COMMANDFILE entry in the item list.
Table 6-1 Valid Masks for the TPU$K_OPTIONS Item Code
GET_INFO
Request
Mask(1) String(2) Description
TPU$M_ COMMAND If TPU senses the presence of
COMMAND the TPU$_COMMANDFILE item, it tries
to read, compile and execute the
unbound TPU code.
TPU$M_ Not Specifies that TPU should use
COMMAND_ applicable the default command file name of
DFLTED TPU$COMMAND.TPU when reading in the
command file. No error is reported
if the default command file is not
found. TPU$INITIALIZE fails when the
TPU$M_COMMAND_DFLTED bit is set to 0
and no file is specified in the item
list.
TPU$M_CREATE CREATE The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_DEBUG Not If TPU senses the presence of
applicable the TPU$_DEBUGFILE item, it tries to
read the file, and then proceeds to
compile and execute its contents as
TPU statements.
TPU$M_ Not If TPU senses the presence of
DEFAULTS applicable the TPU$_DEFAULTSFILE item, it uses
the specified DECwindows X resource
file to initialize the DECwindows X
resource database.
TPU$M_ DISPLAY If TPU senses the presence of the
DISPLAY TPU$_DISPLAYFILE item, it tries to
image activate the specified image
as its screen manager. When the
bit is 0, TPU uses SYS$OUTPUT
for display and only the READ_LINE
built-in procedure may be used for
input.
TPU$M_INIT INITIALIZATIONIf TPU senses the presence of the
TPU$_INIT_FILE item, it returns the
specified string through the built-
in procedure GET_INFO (COMMAND_LINE,
"INITIALIZATION_FILE"). Processing
of the initialization file is left
to the application.
TPU$M_ JOURNAL If TPU senses the presence of the
JOURNAL TPU$_JOURNALFILE item, it outputs
the keystrokes entered during the
editing session to the specified
file.
Note: VSI recommends the use of
buffer change journaling in new
applications.
TPU$M_MODIFY MODIFY The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_ Not TPU initializes the DECwindows X
NODEFAULTS applicable resource database only with resource
files that the DECwindows toolkit
routine XtApplInitialize loads into
the database.
TPU$M_ NOMODIFY The behavior of TPU is not
NOMODIFY affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_OUTPUT OUTPUT The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_READ READ_ONLY The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_ RECOVER The behavior of TPU is not
RECOVER affected by this bit. Its
interpretation is left to the
application layered on TPU.
TPU$M_ SECTION If TPU senses the presence of the
SECTION TPU$_SECTIONFILE item, it tries to
read the specified file as a binary
initialization file. TPU$INITIALIZE
fails if this bit is set to 1 and
the TPU$_SECTIONFILE item is not
present in the item list.
TPU$M_SEC_ Not If TPU senses the presence of the
LNM_MODE applicable TPU$M_SEC_LNM_MODE item, it looks
only at executive mode logical names
when attempting to read in a section
file.
TPU$M_WORK WORK If TPU senses the presence of
the TPU$_WORKFILE item, it uses the
specifed file for memory management.
If no item list entry is present,
and this bit is set to 1, a file is
created in SYS$LOGIN:.TPU$WORK.
TPU$M_WRITE WRITE The behavior of TPU is not
affected by this bit. Its
interpretation is left to the
application layered on TPU.
Footnotes:
1. The flag prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask
corresponding to the specific field in which the bit is set.
TPU$V_ is a bit number.
2. Most bits in the mask have a corresponding GET_INFO (COMMAND_
LINE) request string.
To create the bits, start with the value 0, then use the OR
operator on the mask (TPU$M . . . ) of each item you want to set.
Another way to create the bits is to treat the 32 bits as a bit
vector and set the bit (TPU$V . . . ) corresponding to the item
you want.
user_arg
OpenVMS usage:user_arg
type: longword (unsigned)
access: read only
mechanism: by value
User argument. The user_arg argument is passed to the user-
written initialization routine INITIALIZE.
The user_arg parameter is provided to allow an application to
pass information through TPU$INITIALIZE to the user-written
initialization routine. TPU does not interpret this data in
any way.
3 – Description
This is the first routine that must be called after establishing
a condition handler.
This routine initializes the editor according to the information
received from the callback routine. The initialization routine
defaults all file specifications to the null string and all
options to off. However, it does not default the file I/O or
call-user routine addresses.
4 – Condition Values Returned
TPU$_SUCCESS Initialization was completed successfully.
TPU$_FAILURE General code for all other errors during
initialization.
TPU$_INSVIRMEM Insufficient virtual memory exists for the
editor to initialize.
TPU$_ No routine has been established to perform
NOFILEROUTINE file operations.
TPU$_NONANSICRT The input device (SYS$INPUT) is not a
supported terminal.
TPU$_RESTOREFAIL An error occurred during the restore
operation.
TPU$_SYSERROR A system service did not work correctly.